Skip to content

Getting started

This page is the JANUS quick start. It takes you from nothing to a working first JANUS connection: a client that can reach one permitted resource and is refused everything else. Follow it in order; each checkpoint tells you what you should see.

The example throughout is a fictional operator, Northwind Logistics: one deployment, one gateway, one user, one device, one resource. Substitute your own names as you go. The same example appears in the configuration reference, so the objects you write here match the reference exactly.

What you will end up with

alice-laptop  --WireGuard-->  fra-01-gw1  -->  frankfurt-fileserver:22   (permitted)
                                              anything else            (dropped)

Before you start

Requirement Notes
Two hosts (or one, for a trial) Debian 13 for both the Controller and the Gateway
sudo on both hosts installation, service management and enrolment
PostgreSQL 15+ reachable from the Controller host
A Git repository the source of truth for desired state. Any Git server you already run; a local bare repository is fine for a trial
DNS name + TLS certificate for the Controller's HTTPS front door. The gateway agent talks to it over the network, so a real FQDN with a trusted certificate is the supported case

Packages are built per release and installed locally with apt or dpkg. The examples below write <version> where the actual package version goes (for example X.Y.Z).

Step 1 — Install the Controller

# on the Controller host
sudo apt-get install -y ./janus-controller_<version>_amd64.deb

The package installs the Controller, the WebUI and the self-service portal, and creates the janus-controller system user. It does not install a database.

Create the database and role:

sudo -u postgres psql <<'SQL'
CREATE ROLE janus LOGIN PASSWORD 'change-me';
CREATE DATABASE janus OWNER janus;
SQL

Give the Controller the password through its environment file (/etc/janus/controller.env, installed 0640 root:janus-controller):

JANUS_DB_PASSWORD=change-me

Then edit /etc/janus/controller.yaml for your environment — the database, your Git repository and the listeners. Every field is documented in Install a Controller.

Start the services:

sudo systemctl start janus-controller janus-webui janus-portal
systemctl status janus-controller janus-webui janus-portal --no-pager

Checkpoint. janus-controller is active (running) and the WebUI listens on its loopback port. The administrative API is deliberately not usable yet — see the next step.

Step 2 — Create the first administrator

There is no default credential. Until an administrator exists, administrative routes fail closed. Create the first administrator from the Controller host:

sudo -u janus-controller /usr/bin/janus-controller admin bootstrap \
  --username admin --password-file /etc/janus/credentials/bootstrap.txt

The password is read from a file or stdin — never from the command line, where it would appear in the process list. The file must be a regular file with no group or other access. See Security model for the rules.

If you are scripting rather than signing in to a browser, also issue an API token for the operator CLI:

sudo -u janus-controller /usr/bin/janus-controller admin create-token \
  --username admin --name ops-cli --scopes gateway:read,gateway:admin --ttl 24h

The token is printed exactly once. Point the CLI at your front door:

export JANUS_CONTROLLER_URL=https://janus.example.com

Checkpoint. janus-controller admin status reports the bootstrap state, and you can sign in to the WebUI with the account you just created.

Step 3 — Declare the deployment

Desired state lives in Git. Write these three objects into your configuration repository (see Configuration for the file layout). The platform-scoped objects sit at the repository root:

tenants/northwind.yaml

apiVersion: janusaccess.net/v1alpha1
kind: Tenant
metadata:
  name: northwind
  displayName: Northwind Logistics
spec:
  enabled: true
  entitlements:
    - remote-access

gatewaynodes/fra-01.yaml

apiVersion: janusaccess.net/v1alpha1
kind: GatewayNode
metadata:
  name: fra-01
spec:
  enabled: true
  country: DE
  region: HE
  city: Frankfurt
  sharing: shared
  capabilities:
    - remote-access

deployments/northwind-prod.yaml

apiVersion: janusaccess.net/v1alpha1
kind: Deployment
metadata:
  name: northwind-prod
spec:
  tenant: northwind
  capabilities:
    - remote-access
  placement:
    gateways:
      - fra-01
  network:
    internalPrefixes:
      - 10.0.0.0/8

A Tenant is the ownership and entitlement boundary. A GatewayNode is infrastructure: what a host can technically run. A Deployment is the unit of policy, addressing and runtime domains, and it names the node it may be placed on. Capability, entitlement and placement are three separate declarations on purpose.

Validate before you push — the Controller can check a directory of objects without a database:

janus-controller config validate --path /path/to/config-repo

Checkpoint. OK: configuration is valid.

Step 4 — Add the gateway and enrol it

northwind-prod/gateways/fra-01-gw1.yaml

apiVersion: janusaccess.net/v1alpha1
kind: Gateway
metadata:
  name: fra-01-gw1
spec:
  enabled: true
  gatewayNode: fra-01
  location:
    country: DE
    region: HE
    city: Frankfurt
  wireguard:
    listenPort: 51820
    endpoint: gw.example.net:51820
  capabilities:
    remoteAccess: true
    siteToSite: true
    bgp: false
    publicPrefixes: true
    nat: true
  network:
    allowedPublicIPv4:
      - 203.0.113.0/24

Now install JANUS on the gateway host:

# on the gateway host
sudo dpkg -i janus-gateway_<version>_amd64.deb

Point it at the Controller in /etc/janus/gateway.yaml (the agent's own listener stays on loopback and is not exposed):

controller:
  url: https://janus.example.com
  caFile: /etc/janus/credentials/controller-ca.crt
identity:
  file: /var/lib/janus/gateway/identity.json
agent:
  listen: :9443
  stateDir: /var/lib/janus/gateway/state

Create the gateway's identity and request enrolment:

sudo -u janus-gateway /usr/bin/janus-gateway enroll --wait
created new gateway identity jg_... (fingerprint SHA256:...)
enrollment requested
  gateway id:  jg_...
  fingerprint: SHA256:...
  state:       pending

Enrolment is not automatic: an administrator compares the fingerprint out of band and approves it. Approval is what creates durable trust.

janus enrollment list --state pending
janus enrollment show <gateway-id>
janus enrollment approve <gateway-id>

Checkpoint. janus-gateway status reports the gateway as approved, and --wait returns approved: gateway <id> is trusted.

Step 5 — Start the gateway and verify it is working

sudo systemctl start janus-gateway
janus-gateway status

Then confirm the Controller agrees. The four states are independent, and you should see them converge rather than assume they have:

State Where to look What "good" looks like
Desired Controller → the Deployment's runtime view the gateway has desired state for this deployment
Delivered Controller → runtime view the state reached the gateway and validated there
Applied Controller → runtime view, and the gateway's /api/v1/readyz the kernel reflects the applied artifact
Observed Controller → runtime view runtime signals only — handshakes, activity

Checkpoint. The gateway is applied, and its readiness endpoint answers 200. firewall_state_mismatch in a 503 means the gateway received state but the kernel does not match it — see Troubleshooting.

Nothing is connected yet

There are no users, devices or policies, so nothing can connect. That is the correct state: JANUS denies by default.

Step 6 — Create the user, the resource and the device

Add the access objects to the deployment directory.

northwind-prod/users/alice.yaml

apiVersion: janusaccess.net/v1alpha1
kind: User
metadata:
  name: alice
  displayName: Alice Meyer
spec:
  enabled: true

northwind-prod/resources/frankfurt-fileserver.yaml

apiVersion: janusaccess.net/v1alpha1
kind: Resource
metadata:
  name: frankfurt-fileserver
spec:
  enabled: true
  addresses:
    - 10.20.0.10/32
  gateway:
    primary: fra-01-gw1

northwind-prod/devices/alice-laptop.yaml

apiVersion: janusaccess.net/v1alpha1
kind: Device
metadata:
  name: alice-laptop
spec:
  owner: alice
  enabled: true
  wireguard:
    publicKey: <the device's WireGuard public key>
    ipv4: 10.255.0.10/32
  gateway:
    primary: fra-01-gw1

Two things are deliberate here:

  • The device's public key is the client's own. Generate the keypair on the device. JANUS never generates, receives or stores a client private key.
  • enabled is an access state, not an activity state. It means the device is declared and authorized. It does not mean it is connected.

A device is normally created for you by the enrolment flow rather than by hand; both paths produce the same declarative object. See Client.

Step 7 — Grant access

northwind-prod/accesspolicies/alice-fileserver-ssh.yaml

apiVersion: janusaccess.net/v1alpha1
kind: AccessPolicy
metadata:
  name: alice-fileserver-ssh
spec:
  subject:
    user: alice
  destination:
    resource: frankfurt-fileserver
  services:
    - protocol: tcp
      port: 22
  enabled: true

Exactly one subject (user, group, device or prefix) and exactly one destination (resource or internet) per policy. Only explicitly enabled policies grant anything.

Optionally give the deployment Internet access as well — note that this is a separate grant and does not widen the internal one:

northwind-prod/accesspolicies/logistics-internet.yaml

apiVersion: janusaccess.net/v1alpha1
kind: AccessPolicy
metadata:
  name: logistics-internet
spec:
  subject:
    user: alice
  destination:
    internet: true
  services:
    - {protocol: udp, port: 53}
    - {protocol: tcp, port: 443}
  enabled: true

destination: internet grants the deployment's INTERNET class — never 0.0.0.0/0, and never an internal destination. It also needs a NAT policy to be translated on IPv4; see Internet egress.

Checkpoint. After the Controller reconciles, the resource is applied on the gateway and the policy appears in the deployment's authorization view.

Step 8 — Get the client configuration and connect

On the device, generate a WireGuard keypair, then register the public key and enrol. The self-service portal does this in a browser; the same operation is available to the CLI (janus enrollment/janus-client) and as POST /api/v1/self/devices. Either way:

  1. the device presents its public key;
  2. JANUS creates the Device object and assigns it an address;
  3. JANUS returns a WireGuard client configuration assembled server-side.

That configuration contains the client's own private key, the gateway's public key and endpoint, the client's assigned addresses, and an allowedIPs list equal to the compiled authorization — not a catch-all. Assembly fails closed: a profile with no assigned address, no registered key or no gateway produces no configuration at all. The full contract is in Client.

Import it and bring the tunnel up, then confirm the connection:

sudo wg show
janus-client status        # if you use the JANUS client daemon

Checkpoint. The tunnel is up and a handshake has completed. The device now appears in the runtime view with a real handshake signal — remember that activity comes from that signal, never from the fact that the object is enabled.

Step 9 — Prove it works, in both directions

Do not stop at "it connected". Verify permit and deny, because a misconfiguration that permits everything looks identical to success:

# permitted: the resource, on the port the policy allows
nc -vz 10.20.0.10 22
Connection to 10.20.0.10 22 port [tcp/ssh] succeeded!
# denied: a port the policy does not allow on the same resource
nc -vz 10.20.0.10 8080
nc: connect to 10.20.0.10 port 8080 (tcp) failed: Connection timed out
# denied: another internal address that no policy names
nc -vz 10.20.0.11 22
nc: connect to 10.20.0.11 port 22 (tcp) failed: Connection timed out

The first succeeds, the others are dropped on the gateway's forward path. If the denied cases also succeed, stop and check that your policy is what you think it is — see Troubleshooting.

You now have a working JANUS deployment. Two more checks are worth doing once, because they are the behaviours that matter afterwards:

# 1. Withdraw the grant and watch access disappear without a restart
#    (set spec.enabled: false, commit, let the controller reconcile)
nc -vz 10.20.0.10 22      # now refused

# 2. Stop the Controller and confirm the data plane keeps enforcing
sudo systemctl stop janus-controller
nc -vz 10.20.0.10 22      # still permitted: last-known-good is enforced
nc -vz 10.20.0.11 22      # still refused
sudo systemctl start janus-controller

An expired policy (spec.expires) stops granting access without any new commit.

Where to go next

I want to… Go to
Understand what I just built Architecture overview
Learn the object model properly Configuration
Let clients reach the Internet Internet egress
Connect a customer site Site Edge
Join a second gateway node Gateway agent
Operate it day to day Operations
Use the browser WebUI
Look up a command or an API call CLI · API · Client
Fix something Troubleshooting