mirror of
https://github.com/0xJacky/nginx-ui.git
synced 2026-09-03 07:24:52 +08:00
113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# Command Line Interface
|
|
|
|
The `nginx-ui ctl` command manages a running Nginx UI instance through its
|
|
management API. It is intended for infrastructure-as-code, configuration-as-code,
|
|
deployment automation, and remote administration.
|
|
|
|
## Create an access token
|
|
|
|
1. Sign in to Nginx UI as an administrator.
|
|
2. Open **Preferences > Access Tokens**.
|
|
3. Create a token with the smallest required scope and an expiration date.
|
|
4. Copy the token immediately. Nginx UI does not display it again.
|
|
|
|
The API scopes are:
|
|
|
|
| Scope | Access |
|
|
| --- | --- |
|
|
| `api:read` | `GET`, `HEAD`, and `OPTIONS` management API requests |
|
|
| `api:write` | Mutating management API requests and API read access |
|
|
|
|
MCP scopes are independent of API scopes. Granting `mcp:write` does not grant
|
|
management API access, and granting `api:write` does not grant MCP access.
|
|
|
|
Service tokens cannot access interactive account security operations, reveal
|
|
protected settings, manage other service tokens, or open the web terminal.
|
|
Use an authenticated administrator session for those operations.
|
|
|
|
## Configure the client
|
|
|
|
Set the endpoint and keep the token in a file readable only by the account that
|
|
runs the automation:
|
|
|
|
```bash
|
|
export NGINX_UI_CTL_ENDPOINT=https://nginx-ui.example.com
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list
|
|
```
|
|
|
|
The endpoint can also be supplied with `--endpoint` or
|
|
`NGINX_UI_CTL_ENDPOINT`. The token can be supplied through
|
|
`NGINX_UI_CTL_TOKEN`, `--token-file`, or `--token-stdin`. Prefer a secret file
|
|
or standard input so the token does not appear in command history or process
|
|
arguments.
|
|
|
|
For a private certificate authority, pass its PEM bundle with `--ca-file`.
|
|
Use `--node-id` to route a supported request to a specific cluster node.
|
|
|
|
## Common operations
|
|
|
|
List and create users:
|
|
|
|
```bash
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token users create \
|
|
--name deploy-user --password-file /run/secrets/deploy-user-password
|
|
```
|
|
|
|
The predefined-user environment variables remain useful for the initial user
|
|
in skip-installation deployments. Use `ctl users create` for users managed
|
|
after the instance has started.
|
|
|
|
List certificates and register certificate files that already exist on the
|
|
Nginx UI server:
|
|
|
|
```bash
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token certificates list
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token certificates import \
|
|
--name example.com \
|
|
--cert /etc/nginx/ssl/example.com/fullchain.pem \
|
|
--key /etc/nginx/ssl/example.com/privkey.pem
|
|
```
|
|
|
|
The dedicated certificate commands omit certificate and private-key PEM data
|
|
from their output so CI logs do not capture key material.
|
|
|
|
Inspect and control Nginx:
|
|
|
|
```bash
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx status
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx test
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx reload
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx restart
|
|
```
|
|
|
|
## Call any management API
|
|
|
|
The generic `api` command provides coverage for management operations that do
|
|
not have a dedicated command:
|
|
|
|
```bash
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token api sites?page=1
|
|
nginx-ui ctl --token-file /run/secrets/nginx-ui-token api \
|
|
--method POST --data-file site.json sites
|
|
```
|
|
|
|
Paths are resolved below `/api`. Query strings are preserved, but absolute URLs
|
|
are rejected so credentials cannot be redirected to another host. Request and
|
|
response bodies are limited to 16 MiB.
|
|
|
|
## Token lifecycle
|
|
|
|
Creating, rotating, and revoking service tokens requires an interactive
|
|
administrator token, including any required two-factor verification:
|
|
|
|
```bash
|
|
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens list
|
|
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens create \
|
|
--name ci --scope api:write --expires-at 2027-01-01T00:00:00Z
|
|
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens rotate TOKEN_ID
|
|
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens revoke TOKEN_ID
|
|
```
|
|
|
|
Rotation invalidates the previous token immediately. Revocation is permanent.
|