> For AI agents: the complete documentation index is available at https://www.jumpserver.com/docs/llms.txt, the full documentation bundle is available at https://www.jumpserver.com/docs/llms-full.txt.

# Configuration

JumpServer reads its runtime settings from a single environment-style file,
`/opt/jumpserver/config/config.txt`. The installer generates the file from
`config-example.txt`, then the containers read the values at start time. This page
explains the file, the main groups of settings, and how to change them safely. The
complete parameter list is outside the scope of this page; the installer's
`config-example.txt` documents every option.

## Configuration file

The default location is:

```sh
/opt/jumpserver/config/config.txt
```

Settings use the `KEY=VALUE` form, one per line. The file controls the database and
cache connection, exposed ports, session cookies, logging, component switches,
object storage, and account vault integration. TLS certificate files referenced by
these settings are stored under `/opt/jumpserver/config/certs` and
`/opt/jumpserver/config/nginx/cert`.

## Apply changes

Configuration is not hot-reloaded. Back up the file, edit it, then restart the
services:

```sh
cp /opt/jumpserver/config/config.txt /opt/jumpserver/config/config.txt.bak.$(date +%F)
vi /opt/jumpserver/config/config.txt
./jmsctl.sh restart
```

For changes that affect database or cache connectivity, stop the services first so
that components do not reconnect to a half-written configuration:

```sh
./jmsctl.sh stop
./jmsctl.sh start
```

The installer also provides a guided editor: `./jmsctl.sh config --help` lists the
`ntp`, `init`, `port`, `ssl`, and `env` subcommands. See
[Command-Line Tools](https://www.jumpserver.com/docs/operations/cli-tools.md).

## Main setting groups

| Area               | Representative settings                                                                                                            | Notes                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Persistence        | `VOLUME_DIR`                                                                                                                       | Root of recordings, logs, and database backups. Confirm it before installation; moving it later requires migrating the data. |
| Secrets            | `SECRET_KEY`, `BOOTSTRAP_TOKEN`, `CHAT_AI_DELEGATION_SECRET`                                                                       | Generated at installation. Keep them identical across nodes and when restoring an environment.                               |
| Database and cache | `DB_ENGINE`, `DB_HOST`, `DB_PORT`, `DB_USE_SSL`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_USE_SSL`, `REDIS_SENTINEL_*` | Use external services in production. TLS requires the CA file under `config/certs`.                                          |
| Access             | `HTTP_PORT`, `HTTPS_PORT`, `SERVER_NAME`, `DOMAINS`                                                                                | `DOMAINS` is the trusted-host allowlist; access is rejected with 400/403 when it does not match.                             |
| Components         | `CORE_ENABLED`, `KOKO_ENABLED`, `CHEN_ENABLED`, `WEB_ENABLED`, and similar                                                         | Set a component to `0` to disable it on this host.                                                                           |
| Logging            | `LOG_LEVEL`, `SYSLOG_ADDR`, `SYSLOG_FACILITY`, `SYSLOG_SOCKTYPE`                                                                   | Forward component logs to an external Syslog server.                                                                         |
| Sessions           | `SESSION_COOKIE_AGE`, `SESSION_COOKIE_SECURE`, `CSRF_COOKIE_SECURE`                                                                | Cookie lifetime and transport security. Enable the secure flags when HTTPS is used.                                          |
| Recordings         | `SERVER_REPLAY_STORAGE`, `OPERATE_LOG_ELASTICSEARCH_CONFIG`                                                                        | Object storage for replays and Elasticsearch for operation log changes.                                                      |

## Example: switch to an external database

1. Stop the services with `./jmsctl.sh stop`.
2. Edit `DB_ENGINE`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, and
   `DB_PASSWORD` in `config.txt`.
3. Start the services with `./jmsctl.sh start`.
4. Run `./jmsctl.sh status` and open `http://<jumpserver-host>/api/health/` to
   confirm that Core is healthy.


Warning

Changing the database after data exists does not migrate the records. Move the data
first, or use the restore procedure in [Backup & Restore](https://www.jumpserver.com/docs/operations/backup-restore.md).

## Related topics

- [Command-Line Tools](https://www.jumpserver.com/docs/operations/cli-tools.md)
- [Enable HTTPS](https://www.jumpserver.com/docs/operations/enable-https.md)
- [Backup & Restore](https://www.jumpserver.com/docs/operations/backup-restore.md)
- [Security Hardening](https://www.jumpserver.com/docs/operations/security-hardening.md)