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 |  1) |
| /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) |
1) Time in seconds. 2) Amount in bytes.
These variables can be requested in raw form (last column), to be used from the management console by adding? raw to the URI
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 1) |
| 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 |
1) The response time is defined as the waiting time plus request handling. After the request handling the client receives a status code and the response
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.
When leaving debug mode, the folder and its content are destroyed.
Saving incoming data in the \dump folder decreases performance, thus Debug mode is NOT recommended unless actual debugging takes place.