Ubiquiti cli tool: ucfg

Ubiquiti cli tool: ucfg

Instructional Manual for Using the Ubiquiti CLI Tool ucfg

Introduction

The Ubiquiti CLI tool ucfg is a command-line interface for system configuration management on Ubiquiti devices. This manual provides a comprehensive guide to using the tool effectively based on its actual commands and options.

---

Prerequisites

1. Device Requirements:
   • A Ubiquiti device with CLI support (e.g., UniFi switches, routers, or access points).
   • Ensure the device firmware includes the ucfg tool.
2. Access Requirements:
   • SSH access to the Ubiquiti device.
   • Administrator credentials.
3. Client Requirements:
   • A terminal emulator (e.g., PuTTY, Terminal, or any SSH client).
4. Network Requirements:
   • Ensure the device is reachable over the network.

---

Usage Syntax

The general syntax of the ucfg tool is as follows:

ucfg ([-d] | [-t]) [-h] [-S] <command> ...

Options:

• -d, --debug: Enable debugging output for detailed information during execution.
• -t, --trace: Enable tracing output for more granular command behavior details.
• -h, --help: Display the help message with a list of available commands.
• -S, --silent: Suppress output to stdout.

---

Available Commands

1. Boot Early

Perform actions needed for early boot:

ucfg boot-early [-h]

Options:

• -h, --help: Show the help message and exit.

2. Start the System

Start the system using a configuration file:

ucfg start [-h] [<path>]

Arguments:

• path: Path to a file containing configuration to start from.

Options:

• -h, --help: Show the help message and exit.

3. Stop the System

Stop the system:

ucfg stop [-h]

Options:

• -h, --help: Show the help message and exit.

4. Commit Configuration

Save the active configuration to persistent memory:

ucfg commit [-h] [<path>]

Arguments:

• path: Path to a file containing the configuration to commit.

Options:

• -h, --help: Show the help message and exit.

5. Reset to Factory Defaults

Reset the system configuration to factory defaults:

ucfg defaults ([-r] | [-R]) [-h]

Options:

• -r, --reload: Reload configuration after resetting.
• -R, --reboot: Reboot the device after resetting.
• -h, --help: Show the help message and exit.

6. Reload Configuration

Reload the system configuration:

ucfg reload [-h] [-c] [-C] <path>

Arguments:

• path: Path to a file containing the new configuration.

Options:

• -c, --commit: Commit configuration after reload.
• -C, --continuous: Reload configuration again if it changes during the reload.
• -h, --help: Show the help message and exit.

7. Backup Management

Manage system backups:

ucfg backup [-h] <command> ...

Commands:

• create: Create a system backup.
• validate: Validate a system backup: ucfg backup validate [-h] <path> Arguments:
  • path: Path to a file containing the system backup.
  Options:
  • -h, --help: Show the help message and exit.
• restore: Restore system from a backup: ucfg backup restore [-h] [-r] [-N] <path> Arguments:
  • path: Path to a file containing the system backup.
  Options:
  • -h, --help: Show the help message and exit.
  • -r, --reload: Reload configuration after done.
  • -N, --no-validate: Do not validate configuration before restoring.

8. Edit Configuration

Edit and load configuration using a filter expression:

ucfg edit [-h] [-c] [<filter>]

Arguments:

• filter: Modify the configuration using a jq-like filter expression.

Options:

• -c, --commit: Commit configuration after editing.
• -h, --help: Show the help message and exit.

9. Show Configuration

Display the current configuration in a human-readable format:

ucfg show [-h] [<path>]

Arguments:

• path: Path to a file containing the configuration to show.

Options:

• -h, --help: Show the help message and exit.

10. Migrate Configuration

Migrate configuration to a specific version:

ucfg migrate [-h] <old_path> <target_version> <new_path>

Arguments:

• old_path: Path to the configuration file to be migrated.
• target_version: Version to migrate to.
• new_path: Path where the migrated configuration should be saved.

Options:

• -h, --help: Show the help message and exit.

---

Examples

1. Debugging Mode

Enable detailed output to troubleshoot configuration issues:

ucfg -d show

2. Reset to Factory Defaults with Reboot

Reset the system to its original state and reboot:

ucfg defaults -R

3. Commit Changes

Save active changes to persistent memory:

ucfg commit

4. Show Current Configuration

Display the current device configuration:

ucfg show

5. Start the System with a Specific Configuration

Start the system using a configuration file:

ucfg start /path/to/config.json

6. Create a Backup

Create a system backup:

ucfg backup create

7. Validate a Backup

Validate a system backup:

ucfg backup validate /path/to/backup.file

8. Restore a Backup Without Validation

Restore a backup and skip validation:

ucfg backup restore -N /path/to/backup.file

---

Troubleshooting Tips

1. Enable Debugging: Use the -d option for detailed logs to troubleshoot errors: ucfg -d <command>
2. Test Changes: Use the -t option to test commands without applying them: ucfg -t <command>
3. Restore Backups: Use the backup command to recover previous configurations: ucfg backup restore
4. Check for Help: Refer to the help message for clarification on available commands: ucfg -h

---

Best Practices

1. Backup Regularly: Always create backups before making significant changes.
2. Use Debugging for Troubleshooting: Enable debugging to get detailed insights into operations.
3. Validate Changes in Test Mode: Use the -t flag to test configurations before applying them.
4. Document Configuration Changes: Maintain a log of changes for easier troubleshooting and rollback.

---

Conclusion

The ucfg CLI tool provides robust functionality for managing and configuring Ubiquiti devices. By following this guide, you can effectively utilize the tool to optimize and maintain your network infrastructure.