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 d9abcd7..c2436e3 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 +chirpstack --config /etc/chirpstack reset-password -e admin@example.com -p /tmp/pw.txt + +# Password from stdin (for scripting) +echo "SecurePassword123" | chirpstack --config /etc/chirpstack reset-password -e admin@example.com --stdin +``` + +See [CLI commands](./use/cli-commands.md) for more information. + ## v4.16.1 ### Bugfixes diff --git a/src/chirpstack/use/cli-commands.md b/src/chirpstack/use/cli-commands.md new file mode 100644 index 0000000..76a2de1 --- /dev/null +++ b/src/chirpstack/use/cli-commands.md @@ -0,0 +1,167 @@ +# 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 +echo "SecurePassword123" > /tmp/pw.txt +chirpstack --config /etc/chirpstack reset-password -e admin@example.com -p /tmp/pw.txt + +# Password from stdin (recommended for scripts) +echo "SecurePassword123" | chirpstack --config /etc/chirpstack reset-password -e admin@example.com --stdin +``` + +**Security notes:** + +- When using a file, ensure it has restrictive permissions (e.g., `chmod 600`) +- Always delete password files after use +- When using stdin, ensure the password is not logged in shell history + +**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 +# Create password file with restrictive permissions +echo "SecurePassword123" > /tmp/pw.txt +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