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
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.