Deployment options for handling device -> server connection via HTTPS (certificates). There are a few options how the device is connecting to the Dwarfguard server - in regards of SSL endpoints for the connection. 1. Device --- HTTPS ---> Server - in this simplest case there is no entity in the middle, the device just creates HTTPS connection directly to the server. - there are a few sub-options how to deploy: 1a. Automated default deploy - in automated default deploy, Dwarfguard generates its own, self-signed certificate with 10 years of validity. - the .pem part of the certificate is added to the archive containing agent, so when you install the agent on any device, the .pem file is present on the device, allowing to verify the device is connecting to the right server - the agent configuration defaults to g_security=2, meaning that the server's certificate must be trustworthy (managed by having the .pem file locally available) and there is no option to exchange the certificate for another one. - NOTE that this setup will work 10 years. After certificates expires, devices will be no longer able to verify the server and thus will cease communicating any data to the server. If you need longer timespan fort your system, your options are: - use another setup, prefereably one with certificates signed with certification authority trusted by the devices and automated renewal. NOTE that the setup is outside the Dwarfguard deployment process and needs to be handled by you or a 3rd party. - manually re-generate the certificates before first agent is downloaded and first device installed, specifying longer validity period of the certificate (see 1b) - use lower g_security value by specifying --agent-security [0-2] deployment option when calling the install script. Value 1 allows for certificate exchange when expired (if server provides valid security tokens exchanged when the devices registered). Value 0 disables certificate validation and it is not recommended. NOTE that you can specify the g_security only during initial installation, not later. (see 1c) - NOTE that when you happen to forgot to handle the configuration properly and now your devices have the default g_security=2 (requiring certificate validation) and your server's certificate is expired, there these options how to fix the situation: - generate new certificate on server and re-push agents on your devices using AAD (Automated Agent Deployment) tool. If the devices are not accessible directly from your server (e.g. behind NAT), you can copy the AAD on another device (e.g. Notebook) and move to the network your devices reside on. Note that there are some prerequisities for using the tool like ability to do ssh connection to the devices. - manually (or using a script) change your device configuration of g_security to 0. You can find the variable in /opt/adwarfg/settings.ini. NOTE you need to first stop the agent, make sure it does not run, update the setting and start the agent again. 1b. Automated default deploy with manual post-configuration - once the automated deploy finishes, you can re-generate the certificates by using (since Dwarfguard 1.1.x): - generate your certificate (including CA if you don't have one) - NOTE the exact process and commands depend on your needs and are not part of the Dwarfguard installation process - put the server.key and server.pem files into Dwarfguard installation rootdir - run (inside Dwarfguard installation rootdir) following: ./exchange_server_ip.sh --repack-agents - if the script finishes successfully, it means your new certificates are inside all agent archives. Do not forget to erase any agent archives you may have downloaded prior to the repack - they contain no -longer valid .pem file. You have to you only the actual agent archive 1c. Automated non-default deploy - you can run the installation process also like this: ./install --domain --agent-security 1 OR ./install --domain --agent-security 0 This way you specify different level of g_security value for all your agents than the default. The values means: 2 (the default) ... agent always validates the certificate. If not valid, the data exchange stops. (e.g. once the certificate expires, the agent will not send any data to the server) 1 (allow exchange) ... agent always validates the certificate. If not valid, agent does not sends any device data to the server but allows the server to offer a new vertificate if the server provides the correct security token. NOTE that the security token is obtained on device registration time and never used in deivce < --- > server communication except for the purpose of server certificate exchange 0 (do not check certificate) ... agent does not validate the certificate. NOTE that if the agent archive contains the .pem file, it may, depending on particular device curl version, still validate the certificate against this one particular .pem file. Thus this value of agent security is meaning full only when (A) you are using certificates outside of Dwarfguard purview or (B) Dwarfguard runs in HTTP mode and SSL termiation point is handled prior to data being delivered to Dwarfguard-configured Apache webserver. 2. Device --- HTTPS ---> SSL Termination endpoint --- HTTP ---> Dwarfguard 2a. Semi-automated Dwarfguard-NOSSL default deploy - install with ./install.sh --domain --nossl - Dwarfguard-configured Apache webserver will run on port 80, not providing any SSL - it is ou to you (or 3rd party) to configure the SSL termination endpoint - the SSL termination is usually done on a reverse proxy, e.g. Nginx or Caddy (or another Apache server). - The network connection between the SSL termination endpoint and Dwarfguard must be on a trusted network (or on the same machine) otherwise you risk data being inspected or manipulated. - NOTE that the certificate validity is verified by the devices. See point 1c. if you would like to disable the certificate validation (--agent-security 0) but that's not recommended unless all of your devices and server resides on a single trusted network. - NOTE that you cannot run the whole system completely on HTTP. The device agent always connects over HTTPS so there must be some SSL temrmintation endpoint in the system. 3. Device --- HTTPS (a) ---> SSL Termination endpoint --- HTTPS (b) ---> Dwarfguard - this setup is not recommended. In this setup, there are two different certificates used. - the certificate used for the second HTTPS connection (HTTPS (b)) is not relevant to the device, as the termination endpoint uses a different HTTPS certificate - you (or a 3rd party) is responsible for making the device trusing the CA issuing the certificate for the HTTPS (a) connection. The easiest way is using publicly trusted certificate. The slightly complicated way is making the device trust your internal CA. - NOTE that you cannot use Dwarfguard to deliver the CA trust or a .pem file to the device. - The certificate for the HTTPS (b) connection must be handled outside of the Dwarfguard setup to be not present in the agent archive. - The usual steps to configure this setup are: - install Dwarfguard with ./install.sh --domain --nossl - if using simple files server.key and server.pem for HTTPS (b), put them somewhere outside of Dwarfguard deployment tree on the machine running Dwarfguard - manually edit the Dwarfguard Apache webserver configuration (/opt/dwarfg_.../apache_dwarfg...conf) updating the defined virtualhost from port 80 to port 443 and adding all required configuration directives (e.g. look inside the dwarfg_apache_initial.conf template - but do not use it directly it is just a template missing your domain!) and redirection of HTTP -> HTTPS. - restart Apache2 service - perform configuration of the SSL Termination endpoint as needed