Front-end Service

Introduction

The Front-end service is an HTTP service running on a CapaInstaller Management Server. Simply put. Its job is to act as an information/data hub for CapaInstaller Clients running the BaseAgent. This is our replacement for the SMB access to Management servers for installation files and files generated/to be consumed by the CapaInstaller Replicator Service (REPL). There are a few key points in this scenario:

The Front-end/BaseAgent traffic does not rely on Windows Domain user rights making cross-domain client access an un-issue.
The Front-end can be put in a DMZ and handle client traffic for clients currently on the outside of the firewall. Even without having to put software packages in the DMZ by relaying file requests for a Front-end on the inside of the LAN.
The Front-end/BaseAgent can encrypt traffic (AES 256) on both Internal traffic and public traffic. Encryption on public traffic is default and no certificates are required.
Front-end can intercept calls to .jps files and generate them on the fly from SQL data in order not to link all outside clients to the Front-end in the DMZ.
Front-end runs as a native Windows Service and does not rely on an Internet Information Server (IIS), thus it can be deployed directly from the System plugin.
The Front-end can track units being Online/offline and remote agent runs (from CM) can be carried out even if the Client is outside the firewall.
Front-end also acts an information/data hub for the Mobile Device Management Service (MDM), making profiles commands and software packages available for iOS, Android, and Windows Phone devices.

Requirements

The Front-end Server is a Windows Service that runs on x64 and x86 processors.
The service requires .NET Framework 3.5 to be installed.

Locations

The service is installed from the CapaInstaller console by the ‘System’ plugin.
The service is installed in C:\Program Files\CapaInstaller\Services\CiFrontend
Two log files are written in C:\Program Files\CapaInstaller\Logs\Services during execution; ciFrontEnd.log and ciFrontEnd-Inventory.log

Functionality

Deployment, relays, encryption, and FEStatus are described on these subpages.

Command Line Interface

The service retrieves its configuration from the SQL server but can take different command-line arguments. As the Front-end Server is a windows service, any arguments must be supplied to either the net.exe command or the sc.exe command.

Controlling client bandwidth

To avoid total anarchy, the Front-end Server provides a control mechanism to secure the flow of data for all clients. This is done by limiting (throttling) the bandwidth for clients downloading files. This throttling does not have any effect on the content being downloaded, but is merely adjusting the time being spent on each client. The limit is enforced for every 256KB of data on each download. The bandwidth limit can be set from the command line with the parameter /maxbandwidth=<value> where the value can be something like this; 800k, 2.5m, or 1g (800KB/s, 2.5MB/s or 1GB/s). Furthermore, this value is available on the /config?max bandwidth URI where it can be read and set on runtime.

Parameter syntax:

sc [\\computer] start cifrontend [/debug|/d] [/internalport] [/publicport] [/configport] [/internalencryption]
                                 [publicencryption] [/cmpid] [/maxthreads] [/logroot] [/logconfig] [/loglevel] [/authorization] [/intercept]
                                 [/cachelocation] [/startupdelay] [/httppassword] [relayurl] [/set|clear]

Parameter	Meaning
/debug or /d	Run the service in debug mode.
/skipupdate	Skips the check for a new version from the database
/internalport=##	The internal port, to be accessed from inside the firewall. Default = 80.
/publicport=##	The public port to be accessed from the firewall. Default = 7777
/configport=##	The port to open in order to make the config interface available.
/internalencryption=true\|false	Wether or not encryption is enabled on the internal port. Default = true
/publicencryption=true\|false	Wether or not encryption is enabled on the public port. Default = true
/cmpid=id/fqdn	Sets the default CM Point to use. Either supply an ID of the fqdn of the management point.
/maxthreads=1-(CPU-cores*255)	Sets the maximum number of threads to handle incoming http requests. Default is 100.
/logroot=<path>	Redirect to root of logfiles from %programfiles%\CapaInstaller\Logs
/logconfig=<size,generations>	Sets the size in MB and number of generations of the logfile. Default = 5,10 which is 5 megabytes and 10 generations. Max values are 10,100.
/loglevel=fatal\|error\|info\|debug\|trace	Sets the loglevel of the logfile. Default loglevel is Info.
/authorization= true\|false	Determines if clients must send an Authorization header on the /agent/ uri. The default value is; true
/intercept=true\|false	Intercepts calls to unit files and generates them on the fly. The files are job(.jps), catalog(.xml), calendar(.xml), printer(.xml), powerscheme(.xml) and group(.grp). Default = false
/cachelocation=<path>	Set the path where the cache stores the incoming objects. The default value is %TEMP%\cifrontend
/startupdelay=1-3600	Adds a delay (in seconds) before starting up the service. This argument has no other functionality and is primarily meant for debugging purposes.
/root=root	Changes the root from the defaultvalue; cifrontend.
/skipfirewall	Skips the opening of firewall ports during initialization.
/skipstatistics	Skips adding statistics data to the sql server
/skipunitonline	Skips registering unline status for windows units
/httppassword=<password>	Saves a hash of the password into the registry, that is used as a comparison for password protected endpoints, such as /cifrontend/agents
/relayurl=<url>	Redirects file requests to another Front-end server. For use in the DMZ.

Examples

sc \\frontend01 start cifrontend /d

Start the service on the server; frontend01 in debug mode

sc start cifrontend /cachelocation="D:\FrontEndCache"

Start the service and use D:\FrontEndCache as a cache location.

sc start cifrontend /maxbandwidth=5m

Sets the maximum bandwidth per client to 5MB per second

sc start cifrontend /startupdelay=10 /d

Start the service, and delay the initialization by 10 seconds. Run in debug mode.

sc start cifrontend /internalencryption=false

Sets the encryption flag to false, signaling the base agent to request unencrypted files.

Log levels

Servicing hundreds of thousands of units makes the FrontEnd a busy server. Logging all actions can slow down the server and produce a vast amount of log data. To control the amount of logging, the server uses a log level to select which details to log.

The log level can be set at five different levels;

Log level	Meaning	Example
fatal	Incidents that are fatal for the service	Error reading configuration in SQL server Error retrieving the server node for; server.domain.com
error	Incidents that cause an error for either the server or a client.	Error Checking auto-update Error enrolling device (xx) without a known user
info	Every action has an impact on the server or a client. This includes the initialization of the service.	Existing unit ‘JC’ (running WINDOWS 6.1.7601) (4C4C4544-0043-3010-8050-B2C04F53334A) enrolled on the DevPoint Point The unit ‘DEVTBS’ is now linked to the container \devtbs\devpoint
debug	Debugging information that shows activity but no state changes.	Inserted HWinventory UnitCommand for the iOS device: JH’s iPhone“ APNS: The device ‘dev iPhone’ was told to call home. Tasks: 7 tasks returned for unit: wstst02 Request Win : GET 200 OK (JC) /agent/4C4C4544-0043-3010-8050-B2C04F53334A/file/ms.jpg 89336 0 175
trace	Everything that happens.	Statistics: Memory usage: 57MB -> 62MB PSLimits: 12 PayloadSettingsLimits loaded in 157ms Raw Url 1 : POST - 10.10.100.25 - /cifrontend/agent

When selecting a log level, the higher log levels are included. This means that, if you select the log level; info (command line; /loglevel=info), then Error and Fatal incidents are shown as well;

In debug/trace mode, received inventory data is dumped in \dump that resides alongside the two cache folders; ‘incoming’ and ‘outgoing’. Files dumped herein lives for 24 hours. That leaves enough time to make it possible to harvest incoming inventory data but at the same time minimizes the footprint on the file system.

When leaving debug mode, the folder and its content are destroyed.

The /info URI

The /info URI is used to request the health of the FrontEnd Service. It can be called with a number of specifiers;

Uri	Response	Value
/info/version	Returns the version of the service
/info/time	Returns the time and date of the server
/info/public key	Returns the public RSA key used for encryption
/info/server list	Returns a list of all frontend servers
/info/uptime	Returns the uptime for the service	¹
/info/heartbeat	Returns time since the last heartbeat
/info/memoryusage	Returns the memory usage of the service	[^2][^)]
/info/status	Returns current state
/info/sqlstatus	Shows SQL connection status
/info/cachefiles	Returns the number of files in the incoming cache
/info/cacheworkers	Returns the number of workers on the incoming cache
/info/cacheutilization	Returns how busy the cache is
/info/threadswaiting	Returns the number of threads awaiting execution
/info/threadsactive	Returns the number of active threads
/info/threadutilization	Returns the utilization of threads on incoming calls (%)
/info/utilization	Returns how busy the service is (%)
/info/all	Returns all info variables	(see below)

These variables can be requested in raw form (last column), to be used from the management console by adding? raw to the URI

In addition /info/all can be used. The result will look like this;

Statistics

For each client call made to the FrontEnd server, statistics are collected in a statisticsItem. The properties collected are;

Property	Value	Description
HttpMedtod	POST or GET	This makes it possible to distinguish between the incoming and outgoing flow
IncomingData	Bytes	The amount of data received in the call
OutgoingData	Bytes	The amount of data returned in the call
WaitTime	Milliseconds	The time from the call was registered to work begun
ResponseTime	Milliseconds	The time from the call was registered to response was given ¹
ThreadCount	Integer	The number of threads currently servicing client calls
TimeStamp	Integer	The number of seconds elapsed since January 1. 1970
WaitCount	Integer	The number of threads currently waiting to get served

Each StatisticsItem is collected and summarized and every 30 seconds, the summarized data is written to the SQL server along with application-specific data, which include;

Property	Value	Description	Threshold
Count	Integer	The number of sessions the summary represents	None
MemoryUsage	Bytes	The number of bytes allocated by the FrontEnd Server	Reported if changed more than 10%
Utilization	Integer	The degree of utilization as the number of active threads divided by the maximum number of threads allowed	Reported if changed more than 10% or if it has reached 0
FilesInCache	Integer	The number of unhandled cache elements currently in the cache	Reported if changed more than 10% or if it has reached 0
CacheWorkers	Integer	The Number of threads currently working on the cache	Reported if changed more than 10% or if it has reached 0

Debug mode

The debug mode of the FrontEnd Server serves as an aid in error debugging. The changes in behavior are primarily seen in the log file but a few additional features are used in debug mode.

In Debug mode, received inventory data is dumped in \dump that resides alongside the two cache folders; ‘incoming’ and ‘outgoing’. Files dumped herein lives for 24 hours. That leaves enough time to make it possible to harvest incoming inventory data but at the same time minimizes the footprint on the file system.