Skip to main content

Agent installation

The Orchestration Agent runs on a server to control network access for users on their behalf. This is not an end-user install.

This can be deployed on a small Linux or Windows VM, located alongside a control layer you wish to control - eg: in a firewall management network - or centralized with your Knocknoc Server. You can run multiple, depending on the control infrastructure you're orchestrating. You may run one to manage AWS EC2 on the Knocknoc Server, with another on Windows controlling a Fortinet/Palo Alto, or the native Linux or Windows firewall for bastion/end-host access control. You have options.

  • If your orchestrating server is Linux (bastion SSH/Linux on-host control, small VM, container, etc), follow
    Linux Agent Installation.
  • If your orchestrating server is Windows (orchestrating other systems/devices or controlling RDP locally), follow
    Windows Agent Installation.
  • If your orchestrating in an uncommon environment (eg Solaris SPARC, HP-UX PA-RISC), talk to our team about how we can integrate our Specialized Agent into your environment - contact us now.

You only need to install the Agent on the host that will manage access on Knocknoc’s behalf - your end users do not need any client software.

End users accessing via Knocknoc, do not need to install an agent.

Key material handling/protection

Key material - including tokens or passwords used to access and orchestrate firewalls (etc) - are encrypted using a public/private key-pair, per orchestration Agent. This key material is created on Agent registration, with the public component transmitted to the Server.

The Server utilizes the public-key component to encrypt and store credentials centrally on the Server, with the Agent holding the private key required for decryption. During the grant process, the Server sends the encrypted blob through to the configured Agent for decryption, prior to onward utilization with the relevant control layer, eg firewall.

Therefore a breached Server does not reveal clear-text credentials,  and similarly the encrypted material is not stored permanently on the Agent machine, where the relevant decryption key resides.

It is not possible to retrieve the clear-text credentials for control devices (eg: firewalls) from either side (server/agent) alone, therefore Administrators should take care to backup the Agent configuration folders along with the Server.

Sample configuration file

After you have installed either the Linux or Windows orchestration Agent (not for end users), you will have a configuration file generated as part of the installation.

You will also have a "knocknoc-agent.conf.sample" file, the contents of which are below:

# Knocknoc Agent Configuration File
# ==================================
#
# This file configures the Knocknoc agent to connect to your Knocknoc server.
# The agent receives grant and revoke commands from the server to manage access
# control on firewalls, cloud security groups, and other backends.
#
# Documentation: https://docs.knocknoc.io/books/admin-guide/page/linux-agent-installation
#
# QUICK START:
#   1. Log into your Knocknoc server admin console
#   2. Create a new agent - the server will provide a token
#   3. Run: /opt/knocknoc-agent/knocker/knocker init
#      (This will prompt for the server hostname and token)
#
# Or manually edit this file and set Host and Token below.
#
# Configuration format: TOML (https://toml.io)
# Default location: /opt/knocknoc-agent/etc/knocknoc-agent.conf
#
# After modifying this file, restart the agent:
#   systemctl restart knocknoc-agent
#

# ==============================================================================
# SERVER CONNECTION
# ==============================================================================
#
# You must configure at least one server for the agent to connect to.
# There are two ways to specify servers:
#
# Host name/address/port format:
#   - hostname (e.g., "knocknoc.example.com") - uses default port 443
#   - hostname:port (e.g., "knocknoc.example.com:8756") - custom port
#   - IP:port (e.g., "192.168.1.100:8756")
#
# Insecure flag:
#   - false (default): Verify TLS certificates - use for production
#   - true: Skip TLS verification - only use for testing or self-signed certs
#
# Option 1: Single server (simple)
# --------------------------------
# Use 'Host' and 'Insecure' for a single server connection.
#
#Host = "knocknoc.example.com"
#Insecure = false
#
# Option 2: Multiple servers (high availability)
# ----------------------------------------------
# Use 'Hosts' array for connecting to multiple servers. The agent will
# maintain connections to all configured servers for redundancy.
#
#Hosts = [
#     { Host = "knocknoc1.example.com", Insecure = false },
#     { Host = "knocknoc2.example.com:8756", Insecure = false }
# ]

# ==============================================================================
# AUTHENTICATION
# ==============================================================================
#
# There are two ways to authenticate agents:
#
# Option 1: Manual registration with Token (default)
# --------------------------------------------------
# Create an agent in the server admin console and use the provided token.
#
#   1. Log into your Knocknoc server admin console
#   2. Navigate to Agents and create a new agent
#   3. Copy the token provided by the server
#   4. Paste it here or use 'knocker init' to configure interactively
#
#Token = "paste-your-token-from-the-server-here"
#
# Token can also be stored in a separate file for security:
#TokenFile = "/opt/knocknoc-agent/var/token"
#
# If TokenFile is set and the file exists, the agent reads the token from there.
# This keeps the token out of the main config file.
#
# Option 2: Auto-registration with RegisterKey
# --------------------------------------------
# Agents can register themselves automatically using an API key. This is useful
# for automated deployments where you don't want to manually create each agent.
#
# To use auto-registration:
#   1. Generate a RegisterKey in the server admin console
#   2. Set RegisterKey below (instead of Token)
#   3. Set Name to identify this agent when it registers
#
# The agent will register itself on first connection and receive a token.
#
#RegisterKey = "your-api-key-for-auto-registration"
#
# Note: Only one of Token or RegisterKey may be set, not both.

# ==============================================================================
# AGENT IDENTITY
# ==============================================================================
#
# Name: A human-readable name for this agent.
# This is only used when auto-registering with RegisterKey - the agent will
# register itself with this name in the server. For manually created agents
# (using Token), the name is set in the server admin console.
#
#Name = "firewall-agent-dc1"
#

# ==============================================================================
# SECURITY
# ==============================================================================
#
# CustomScripts: Allow the server to trigger custom scripts on this agent.
# When enabled, the server can execute scripts in /opt/knocknoc-agent/scripts/
# for backends that use script-based ACL management.
#
# - false (default): Disable custom scripts for security-restricted environments
# - true: Allow custom script execution (required for script-based backends)
#
#CustomScripts = false
#
# KeysFile: Location of the agent's cryptographic keys (auto-generated on first run).
# The agent uses these keys for secure communication with the server.
# We recommend you back up this key material, the data is encrypted and stored 
# inside the Server database, however is unrecoverable without these keys.
#
#KeysFile = "/opt/knocknoc-agent/var/keys.json"
#

# ==============================================================================
# WINDOWS-SPECIFIC SETTINGS
# ==============================================================================
#
# These settings only apply when running the agent on Windows.
#
# WindowsLogLocation: Path for Windows event log output
# WindowsRulePrefix: Prefix for rule names consumed and made visible to the Admin
#
#WindowsLogLocation = 'C:\Program Files (x86)\Knocknoc-Agent\logs'
#WindowsRulePrefix = 'kn_'
#

# ==============================================================================
# LOGGING
# ==============================================================================
#
# LogLevel: Controls verbosity of agent logs.
# Values: Trace, Debug, Info, Warn, Error (case-insensitive)
# Default: Info
#
#LogLevel = "Info"
#
# LogTimestamp: Include timestamps in log output.
# Default: false (systemd/journald adds timestamps automatically)
#
#LogTimestamp = false
#

# ==============================================================================
# HTTP PROXY SETTINGS
# ==============================================================================
#
# Configure proxy settings if the agent needs to connect through a proxy
# to reach the Knocknoc server.
#
# HttpProxy: Proxy URL for HTTP connections
# HttpsProxy: Proxy URL for HTTPS connections
# NoProxy: List of hosts/domains to bypass the proxy
#
#HttpProxy = "http://proxy.example.com:8080"
#HttpsProxy = "http://proxy.example.com:8080"
#NoProxy = ["localhost", "127.0.0.1", "*.internal.example.com"]
#

# ==============================================================================
# MINIMAL EXAMPLE CONFIGURATION
# ==============================================================================
#
#Host = "knocknoc.example.com"
#Token = "your-token-from-server"
#

# ==============================================================================
# FULL EXAMPLE CONFIGURATION
# ==============================================================================
#
#Name = "datacenter-firewall-1"
#Host = "knocknoc.example.com"
#Token = "your-token-from-server"
#Insecure = false
#CustomScripts = false
#LogLevel = "Info"
#

# ==============================================================================
# HIGH AVAILABILITY EXAMPLE
# ==============================================================================
#
#Hosts = [
#     { Host = "knocknoc1.example.com", Insecure = false },
#     { Host = "knocknoc2.example.com", Insecure = false }
# ]
#Token = "your-token-from-server"
#CustomScripts = false
#

# ==============================================================================
# AUTO-REGISTRATION EXAMPLE
# ==============================================================================
#
# Use this for automated deployments where agents register themselves.
#
#Name = "firewall-agent-dc1"
#Host = "knocknoc.example.com"
#RegisterKey = "your-api-key-for-auto-registration"
#CustomScripts = false
#

Back to top