Skip to main content

Server Installation

For the admin who knows what they need and needs a fast way to get it, you can use this command to setup and install your Knocknoc server very quickly. 

curl -sSL https://packages.knocknoc.io/setup/setup_knocknoc.sh | bash 

The installer runs on Debian, Ubuntu, Redhat, Oracle and Amazon Linux.

Note - you need a license to use Knocknoc server, the details can be found here.

If you want to use our SaaS/Cloud offering to get started quickly, spin up an instance via the licensing portal here.

Requirements

Knocknoc server is the component that users will authenticate to, and agents will connect to over port 443. So the following is required to operate a self hosted Knocknoc server:

  • Linux machine running an up to date Debian or Redhat derivative 
  • Static IP, ideally with DNS name.
  • Inbound port 443 open
  • Minimal system requirements (2G RAM, 1 CPU, 10G disk). A busy production server would benefit from >4G RAM, 2 CPUs and faster disk.
  • SSL key/certificate. Note that a self-signed or Let's Encrypt is created during the install process. 

If you meet these requirements, please go ahead and try out Knocknoc as per below. if you are hosting Knocknoc internally, you can use a private IP of course, but ideally DNS and SSL work too.

Self-Hosted Servers

  1. Log into your Knocknoc server via the command line and become the root user.
  2. Run this command below to start the installation process. The script will then configure apt, setup secure repository access, and install the Knocknoc server.
    curl -sSL https://packages.knocknoc.io/setup/setup_knocknoc.sh | bash
  3. Accept the License Agreement.
  4. The Knocknoc server will ask for the IP to listen on and the port. By default it will listen on 127.0.0.1:8756. This can be changed to 0.0.0.0:8756 to listen externally if you do not intend to use the HAProxy reverse-proxy installed throughout this process. Please adjust as your firewall or reverse proxy layout requires. See below for ipv4/ipv6 tips, this can be configured later.
  5. The install will then ask for TrustedForwarders, by default 127.0.0.1/32 is entered but if the server is behind a reverse proxy, the IP of the reverse proxy will need to be entered. TrustedForwarders are the machines permitted to send the ForwardFor header to Knocknoc.
  6. Lastly the install will generate an SSL certificate and key, where it will ask you for Organizational Details. Knocknoc only communicates over HTTPS, so this certificate is to get you started, and can be replaced later.
  7. Once the script is completed, it will print the knocknoc-admin password. If you missed the output of the script;
    cat /var/log/syslog |grep knocknoc-admin or journalctl -u knocknoc |grep knocknoc-admin
  8. You are now ready to log into your Knocknoc admin portal.

Accessing the Admin console:

  1. If you chose to bind to 127.0.0.1:8756, you need to install the reverse-proxy component.
    1. Run /opt/knocknoc/knocker/knocker enable haproxy to install and configure the recommended reverse proxy.
    2. Press Y to proceed
    3. Enter the hostname for this server (e.g. knocknoc.yourdomain.com): knocknoc.mydomain.com
    4. If you want IPv6 support for client logins to Knocknoc, choose Y
    5. The installer creates a self-signed cert by default, however also supports Let's Encrypt via CertBot. For testing purposes press 3/enter and accept the self-signed certificate, this can be replaced later. If you want to provision a valid LE certification, use 1 for Standalone or 2 for DNS based.
    6. You can now visit https://YourKnocknoc.url/admin to access via HTTPS and the reverse proxy. This brings other protection benefits and even allows Knocknoc to protect the /admin path!
  2. If you chose to bind to 0.0.0.0:8756, simply browse to https://YourKnocknoc.url:8756/admin and login with the knocknoc-admin user.

Adding a license:

  1. Click on Settings and paste the license key from the license portal and hit save.
  2. You're all set to get started!

SSL Certs - Let's Encrypt and Certbot

During the optional installation of the reverse proxy, you can choose to create a Let's Encrypt SSL key/certificate.

This will use Certbot to obtain a valid, Let's Encrypt CA-signed certificate and install it, along with configuring HAProxy to handle renewals and forward the Knocknoc service.

/opt/knocknoc/knocker/knocker enable haproxy

Enabling backend haproxy on this machine.
Note: Some operations may require sudo rights.
About to enable HAProxy for knocknoc server with SSL:
  1) Install HAProxy, Certbot, and OpenSSL
  2) Write the deploy-hook script (reload only if cert renews, used by Certbot)
  3) Obtain or generate an SSL certificate
  4) Write /etc/haproxy/haproxy.cfg to listen on ports 80/443
  5) Validate the HAProxy config
  6) Enable SELinux port labeling for the knocknoc port (if needed)
  7) Restart HAProxy only if config is valid
  8) (Optional) Set up a systemd timer to renew the certificate daily if Let’s Encrypt is used

Proceed? (y/N): y

Shown below, if port 80 is accessible on your server and DNS is configured, you can obtain a valid certificate in one flow!

# /opt/knocknoc/knocker/knocker enable haproxy

About to enable HAProxy for knocknoc server with SSL:
  1) Install HAProxy, Certbot, and OpenSSL
  2) Write the deploy-hook script (reload only if cert renews, used by Certbot)
  3) Obtain or generate an SSL certificate
  4) Write /etc/haproxy/haproxy.cfg to listen on ports 80/443
  5) Validate the HAProxy config
  6) Enable SELinux port labeling for the knocknoc port (if needed)
  7) Restart HAProxy only if config is valid
  8) (Optional) Set up a systemd timer to renew the certificate daily if Let’s Encrypt is used

Proceed? (y/N): y

Your public IP is: 170.64.155.167 (via ifconfig.me).
You need to point a domain name A record at 170.64.155.167 if you plan to use Let's Encrypt.

Enter the hostname for this server (e.g. knocknoc.yourdomain.com): kk.example.org
Enable IPv6 support in HAProxy? (y/N): n

Select certificate method for domain [kk.example.org]:
  1) Let’s Encrypt (Standalone HTTP) - automatically obtains valid certificate
  2) Let’s Encrypt (Manual DNS)      - you manually create a DNS TXT record each time
  3) Self-Signed Certificate         - generates a self-signed cert (browsers show warnings!)
Enter 1, 2 or 3 [Default=3]: 1

Enter your email for Let’s Encrypt registration: ssl@example.org

Obtaining certificate for domain: kk.example.org ...
You chose Standalone HTTP validation. Certbot will listen on port 80 for the first cert. Renewals will be managed via haproxy config.
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Requesting a certificate for kk.example.org
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/kk.example.org/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/kk.example.org/privkey.pem
This certificate expires on 2025-07-08.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
 * Donating to EFF:                    https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Combining the certificate and key into /etc/ssl/private/kk.example.org.pem...
Validating HAProxy config with 'haproxy -c -f /etc/haproxy/haproxy.cfg'...
Configuration file is valid
HAProxy configuration looks valid.
Enabling and restarting HAProxy...
Synchronizing state of haproxy.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable haproxy
Setting up daily systemd timer for certificate renewal...
Created symlink /etc/systemd/system/timers.target.wants/haproxy-cert-renew.timer → /etc/systemd/system/haproxy-cert-renew.timer.
Systemd timer set up. It will run daily to renew the certificate for kk.example.org.
HAProxy will only reload when the certificate is actually renewed.
----------------------------------------------------
HAProxy is configured with a Let’s Encrypt certificate for https://kk.example.org.
A systemd timer is set up to renew the certificate daily (if it’s Let’s Encrypt).
HAProxy will reload ONLY if the cert is actually renewed.
Configuration is in /etc/haproxy/haproxy.cfg.
Done.

You can now browse to https://kk.example.org and enjoy a valid Let's Encrypt certificate.

Server configuration file

The server configuration file (/opt/knocnoc/etc/knocknoc.conf) has a number of options, however the default is typically sufficient.

For IPv4 and IPv6 configurations, ensure you are binding to both or one. Currently this is managed by setting the below:

# knocknoc.conf

# v4 and v6
HTTPAddr = "[::]:8756"

# v6 only
#HTTPAddr = "[::1]:8756"

# v4 only
#HTTPAddr = "127.0.0.1:8756"

If you're using HAProxy or another proxy you need to configure the TrustedForwarders to pick up the end client users IP address, typically for a IPv6 and IPv4 configuration this is done so as below:

TrustedForwarders = [ "::1/64", "127.0.0.1/32" ]

LogLevels can be set as "error" "warn" "info" "debug" "trace", increasing in verbosity.

LogLevel = "info"
#LogLevel = "debug"
#LogLevel = "trace"

Working with outbound Proxies

Knocknoc server requires access out to the licensing portal to activate the license and report anonymous usage for license verification purposes. More information on the data transferred can be found here.

To get knocknoc working through a web proxy, add the proxy environment variable to the systemd unit file.

  1. Edit the systemd unit file.
    sudo systemctl edit knocknoc.service
  2. Add this line under the [Service] section
    Environment="HTTPS_PROXY=http://proxyIPaddress:proxyport"
  3. Reload the systemctl daemon
    systemctl daemon-reload
  4. Restart knocknoc-agent 
    systemctl restart knocknoc

Note that the following URLs are required outbound from the knocknoc server software:

https://licensing.knocknoc.io

Supported Operating Systems

Debian, Ubuntu, Redhat and Oracle Linux are all supported.

If you have any issues or require another platform please contact support@knocknoc.io

Monitoring

We recommend monitoring the/_status route, as it reduces the log impact on your server/infrastructure and offers back-end checking benefits - for a more accurate server status.

Cloud servers (SaaS)

Your cloud instance is ready to go out of the box, with the license installed. You can jump straight to Agent Installation.

Your knocknoc-admin password should be available in the licensing portal, please change it on first login.

Back to top