diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 956eb75..bcce87d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -65,6 +65,7 @@ - [RX parameters (re)configuration](./chirpstack/features/rx-parameters-configuration.md) - [Use](./chirpstack/use/index.md) - [Applications](./chirpstack/use/applications.md) + - [CLI commands](./chirpstack/use/cli-commands.md) - [Device profiles](./chirpstack/use/device-profiles.md) - [Devices](./chirpstack/use/devices.md) - [Event log](./chirpstack/use/event-log.md) diff --git a/src/chirpstack/changelog.md b/src/chirpstack/changelog.md index 0ab4e5c..81b6329 100644 --- a/src/chirpstack/changelog.md +++ b/src/chirpstack/changelog.md @@ -1,5 +1,33 @@ # Changelog +## v4.17.0 + +### Features + +#### CLI reset-password command + +This release adds a new `reset-password` command to the ChirpStack CLI. This +command enables resetting user passwords without API access, which is useful for: + +- Initial setup of fresh installations +- Automated deployment scripts +- Recovery from forgotten passwords + +**Usage:** + +```bash +# Interactive password reset +chirpstack --config /etc/chirpstack reset-password -e admin@example.com + +# Password from file (recommended for scripts) +chirpstack --config /etc/chirpstack reset-password -e admin@example.com -p /tmp/pw.txt + +# Password from stdin (e.g. piped from a secrets manager) +my-secrets-tool get admin-password | chirpstack --config /etc/chirpstack reset-password -e admin@example.com --stdin +``` + +See [CLI commands](./use/cli-commands.md) for more information. + ## v4.16.2 ### Bugfixes diff --git a/src/chirpstack/use/cli-commands.md b/src/chirpstack/use/cli-commands.md new file mode 100644 index 0000000..066b8c0 --- /dev/null +++ b/src/chirpstack/use/cli-commands.md @@ -0,0 +1,169 @@ +# Command-line interface + +ChirpStack provides a command-line interface (CLI) for tasks such as resetting +user passwords, creating API keys, and managing device profiles. These commands +are useful for automated deployments, scripting, and administration. + +## Usage + +The CLI is invoked using the `chirpstack` command: + +```bash +chirpstack --config [OPTIONS] +``` + +Where `--config` points to the ChirpStack configuration directory (containing +`chirpstack.toml` and region configuration files). + +## Available commands + +### reset-password + +Reset a user's password without API access. This command is useful for: + +- Initial setup of fresh installations +- Automated deployment scripts +- Recovery from forgotten passwords + +**Usage:** + +```bash +chirpstack --config /etc/chirpstack reset-password --email [OPTIONS] +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `-e, --email ` | User email address (required) | +| `-p, --password-file ` | Path to file containing new password | +| `--stdin` | Read password from stdin | + +**Examples:** + +```bash +# Interactive password reset (prompts for password twice) +chirpstack --config /etc/chirpstack reset-password -e admin@example.com + +# Password from file (recommended for scripts) +read -rs PW && printf '%s' "$PW" > /tmp/pw.txt && unset PW +chmod 600 /tmp/pw.txt +chirpstack --config /etc/chirpstack reset-password -e admin@example.com -p /tmp/pw.txt +rm /tmp/pw.txt + +# Password from stdin (pipeline use, e.g. from a secrets manager) +my-secrets-tool get admin-password | chirpstack --config /etc/chirpstack reset-password -e admin@example.com --stdin +``` + +**Security notes:** + +- When using a file, set restrictive permissions (`chmod 600`) and delete it after use +- Avoid embedding a plaintext password in a command (e.g. `echo "pass" | ...`): it appears in shell history and is visible via process inspection +- For scripts, prefer the file method or pipe from a secrets manager — see the [Password handling](#password-handling) table below + +**Password requirements:** + +- Minimum 8 characters +- Maximum 128 characters +- NIST 800-63b compliant (no arbitrary complexity requirements) + +### create-api-key + +Create a global API key for administrative access. + +**Usage:** + +```bash +chirpstack --config /etc/chirpstack create-api-key --name +``` + +**Example:** + +```bash +chirpstack --config /etc/chirpstack create-api-key --name "automation-key" +``` + +Output: + +```bash +id: +token: +``` + +### configfile + +Print the configuration template to stdout. + +**Usage:** + +```bash +chirpstack --config /etc/chirpstack configfile +``` + +### import-device-profiles + +Import LoRaWAN device profiles from a directory. + +**Usage:** + +```bash +chirpstack --config /etc/chirpstack import-device-profiles +``` + +### migrate-device-profile-templates + +Migrate device-profile templates to device profiles. + +**Usage:** + +```bash +chirpstack --config /etc/chirpstack migrate-device-profile-templates +``` + +### print-ds + +Print the device-session for debugging (requires --dev-eui). + +**Usage:** + +```bash +chirpstack --config /etc/chirpstack print-ds --dev-eui +``` + +## Security considerations + +### Password handling + +The CLI provides multiple methods for password input, each with different +security implications: + +| Method | Security | Use case | +|--------|----------|----------| +| Interactive prompt | Highest | Manual administration | +| File (0600 permissions) | Medium | Scripted deployments | +| Stdin | Low | Pipelines (ensure no history) | + +For scripted deployments using password files: + +```bash +# Read password without it appearing in shell history +read -rs PW && printf '%s' "$PW" > /tmp/pw.txt && unset PW +chmod 600 /tmp/pw.txt + +# Use in command +chirpstack --config /etc/chirpstack reset-password -e admin@example.com -p /tmp/pw.txt + +# Immediately delete +rm /tmp/pw.txt +``` + +### Default credentials + +Upon first installation, ChirpStack creates a default admin user with the +credentials: + +- Username: `admin` +- Password: `admin` + +**It is strongly recommended to change this password immediately upon first +login** using either the web interface or the `reset-password` command. \ No newline at end of file