Quick Start

Installation:

  1. Prerequisites: AlmaLinux 8/9 minimal or equivalent (CentOS, Rocky Linux etc), IPv4 internet connection and at least one domain name with your ability to create subdomains and set A records on them. Your server can be behind NAT.
  2. Hardware requirements: 1vCPU, 2GB RAM, 15GB disk space minimum for a non-redundant setup with a few users. Will increase with scaling the user amount up.
  3. Download the installer files from here (SHA256: 94d443419f8f7b2b2e7aea8998261e7b00d9d3412c082af45ef99c038494bb98). Unzip the archive and upload the files to your server to the folder of your choice.
  4. Run the installer.sh script, setting passwords, domain names and other information as requested.
  5. The Shadow server is run and is to be operated on behalf of the user called shadow. The server binary is located at /home/shadow/shadowserver/.
  6. Generate the unidentified access credentials:
    • java -jar ShadowServer-{VERSION}.jar certificate -ca
    • java -jar ShadowServer-{VERSION}.jar certificate -k <CA_private_key> -i <key_id>
  7. Generate the ZK credentials:
    • java -jar ShadowServer-{VERSION}.jar zkparams
  8. Review the configuration file at $HOME/shadowserver/config/shadow.yml and fill in the missing information, including the credentials described above.
  9. For the fcmSenderId credential in the configuration file, create a Firebase project at Google, and use your FCM sender ID. The apiKey credential is now obsoleted. Instead you should download your default Firebase service account JSON file, rename it to service-account.json and place it to $HOME/shadowserver/config/.
  10. Launch the Shadow server:
    • systemctl start shadow
  11. To create a pending client account and generate a registration OTP for that client, execute:
    • java -jar ShadowServer-{VERSION}.jar adduser -u <user_login> ./config/shadow.yml
  12. To remove a client account, execute:
    • java -jar ShadowServer-{VERSION}.jar rmuser -u <user_login> ./config/shadow.yml
  13. You may use comma-separated lists of user logins for the above commands.
  14. To observe the Shadow server console output, use:
    • su shadow
    • tmux a -t shadow
  15. (Optional: for installation with four or more clients) Server activation key must be placed into the /home/shadow/shadowserver/license/ folder and be renamed to shadowserver.bin.
  16. The A record of the offline alarm signaling (sub)domain must be set to 127.0.0.1 during normal operation.
  17. For initial provisioning, a client will need to scan the registration QR-code. Use the following command to generate such QR-code:

java -jar ShadowServer-{VERSION}.jar qrcode -p <your_port_number> ./config/shadow.yml

where the port number matches the one used to access your Shadow server from the Internet. You may omit the port number command parameter, in which case the command will use the value from the configuration file (this will render the communication impossible if your server is behind NAT).

Updating:

Client devices will be notified of available updates by means of Android notifications.

Server needs to be updated manually. Sometimes an upgrade script would be provided. Refer to the release notes for further details and information on whether there are changes in the configuration file format, directory structure or database structure.