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
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¶
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):
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:
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:
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:
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:
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¶
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.
enabledis 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:
- the device presents its public key;
- JANUS creates the
Deviceobject and assigns it an address; - 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:
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:
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 |