Help

Installing Dwarfguard (for non-SAAS deployments)

Requirements

Dwarfguard is generally not very resource-demanding application however it requires proper setup. Also, the consumed resources are depending on a number of devices being managed. To get a clue about the amount of resources required, see more on Performance.

SW requirements

  • Linux OS / 64bit (x86-64)
  • Supported distributions:
    • for Dwarfguard 0.8: Debian 11 GNU/Linux / Debian 12 GNU/Linux
    • for Dwarfguard 1.0: Debian 12 GNU/Linux
    • Other distributions using DEB packages may work but are not supported
    • Manual installation on other distro / UN*X is possible however you would need to rewrite installation scripts as they are relaying on apt (definitely not supported)
  • Installation using root account
  • UTF-8 based locale set on server (e.g. en_US.UTF-8)
  • Systemd for service control
  • Access to standard Debian mirror (during deployment to install required packages (auto-installs all SW for the same machine/node/container mentioned below))
  • Apache2 web server as default and only web server on the machine/node/container
  • For non-self-signed HTTPS certificate:
    • Correctly configured reverse-proxy (e.g. Nginx, WebCaddy), usually on a different machine/node/container (NOT part of Dwarfguard deployment, needs to be configured separately).
      • OR
    • Periodic replacement of certificate in Apache directory and allowing certificate replacement on agents
    • NOTE: self-signed certificates are generated automatically during installation unless you use the --nossl option

HW requirements

  • 1 GiB free space in /opt partition
  • Variable space in /srv partition depending on:
    • Number of firmware cached for offering to devices
    • Log rotation configuration
  • DB storage up to ~200 KiB per registered device.
  • RAM depending on number of devices (see more on Performance)
    • 40 MiB for start, up to 60 KiB for version 0.6 per one connected device
  • CPU highly depending on number of devices (see more on Performance)

Instructions

  1. Grab Dwarfguard package (See available builds)
  2. Grab Dwarfguard license
  3. Copy deploy package somewhere on the target machine/node/container
  4. Uncompress
  5. If performing simple deploy, run
    • ./install.sh --domain <your_domain>
      • the domain must be the URL your devices can use for accessing the server, so a FQDN, DNS alias, or IP address
      • Example domain on the Internet: dwarfg.mydomain.com
      • Example when using your own private network with DNS alias 'mydwarfg' pointing to the server IP: mydwarfg
      • Example when your devices are accessing the server using fixed IP 10.10.10.111: 10.10.10.111
    • Other useful options:
      • --help ... prints supported options
      • --servsshport <ssh-port(for-webtunnels)> ... when your devices need to use specific (other than 22) port for ssh access to your server
      • --admname <admin_email_login> and --admpwd <password> ... if you want to change admin login and/or admin default password during installation
      • --opername <operator_email_login> and --operpwd <password> ... like above but for operator (note that if you want to use operator account, you need to enable it using admin account after installation)
      • --license <absolute_path_to_license_file> ... if you would like to use a different than bundled license file during install (you can replace the license after install either via GUI or simply copying the file, just don't forget to restart the Dwarfguard service afterwards). NOTE: you must provide an absolute path to the license file when using this option, stuff like ./my_license will fail, use "$(pwd)/my_license" instead. NOTE also that to check the license file validity, some libraries are needed and these libraries may not be installed in the system prior Dwarfguard installation. In that case, first install with bundled license and the exchange the license file and restart the service OR run cleanup.sh to remove the deployment and install anew with using --license parameter (libraries are now installed on the system, license validity check can be done)
      • --nossl ... if you use a reverse proxy like caddy or nginx taking care of e.g. automatic certificate refresh or simply run Dwarfguard on a trusted network
      • NOTE: available since version 1.1: --agent-security [0..2] ... Specify global agent forced security level. 2 (default) means check server certificate always, do not allow exchange. 1 means check but allow exchange if security tokens matches. 0 means do not check server certificate (use case = devices and server on VPN, internal CA not trusted by endpoint devices). Not changeable after deployment.
  6. If performing upgrade:
    1. Refer to the upgrading section in Dwarfguard Administration prior upgrading.
  7. Once installed, for new deployment:
    1. Update admin e-mail
    2. Setup slack for alert distribution (if applicable)
    3. Upload license
    4. Add devices, monitoring groups, alerts, firmwares, ...
    5. Note that the domain you used impacts the name of the Dwarfguard service and installation directory. E.g. for install to domain "main", the deployment would use:
      • /opt/dwarfg_main ... as main directory
      • /srv/dwarfg_main ... for data and logs
      • dwarfg_main ... as the systemd service name
  8. Check Dwarfg event log (UI) that no abnormal event occurred.

Deployment options for handling 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 <your_domain> --agent-security 1
  • OR
    • ./install --domain <your_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

  • install with ./install.sh --domain <your_domain> --nossl
  • Dwarfguard-configured Apache webserver will run on port 80, not providing any SSL
  • It is up 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 <your_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
Copyright (c) 2023 by     Wiki is powered by Fossil SCM