Skip to content

Latest commit

 

History

History
40 lines (27 loc) · 3.5 KB

scope.md

File metadata and controls

40 lines (27 loc) · 3.5 KB
Raw

opnsense-cli features

Scope and intent

There is a gap between using OPNsense web GUI that offers fail-safe (but limited) configuration capabilities and using FreeBSD command terminal that offers direct access to all functionality of FreeBSD and OPNsense but exposes a great risk of messing things up for anyone that is not well versed in shell commands.

opnsense-cli utility bridges this gap by providing command-line access to local or remote OPNsense firewall. For remote access, it requires ssh service to be enabled, as it uses ssh to communicate with the firewall. Every action of opnsense-cli is translated to a shell command that is then executed on OPNsense.

Features and Benefits

  • Versatility: Can operate both locally and remotely (via ssh),and is suitable for various deployment scenarios.
  • Transparency and Control: All opnsense-cli Commands are translated to shell scripts (not API calls), with interactive confirmation for critical changes (bypassable with the --force flag).
  • Cross-Platform Support: Works on macOS, Windows, Linux, and OpenBSD.
  • Streamlined Operations: Facilitates repeatable configurations, troubleshooting and complex automations.

Mechanics

opnsense-cli is focusing on config.xml manipulation of OPNsense. All configuration settings are stored in config.xml file and OPNSense web GUI actions primarily change data in config XML elements. To protect the integrity of configuration, opnsense-cli is not changing config.xml directly - all changes are staged in a separate staging.xml file. Configuration elements can be added, removed, modified, discarded and imported - all changes will impact only staging.xml until 'commit' command is issued. That's when opnsense-cli will create a backup of config.xml and replace it with content from staging.xml.

opnsense-cli is also providing commands to manage backup copies in /conf/backup directory of OPNsense. It can show all available backups, display details of a specific backup file (including XML diffs between backup file and config.xml), save, restore, load and delete backup files. It can trim number of backup files based on age and desired count of files in the directory.

opnsense-cli also offers (very basic) system management commands. sysinfo will display core information about OPNsense instance, run command will list and execute all commands that are available through configctl process on OPNsense.

using ssh identity with opnsense-cli

When connecting remotely to OPNsense using ssh, opnsense-cli will try to use private key stored in ssh-agent to authenticate. Only when no identities are present or match the public key on OPNsense server, the fallback to password will be initiated. As opnsense-cli stores no data locally, the password request will pop-up every time when opnsense-cli initiates the ssh call. Very annoying.

To use ssh identity, both server and client need to be configured with the access key. OPNsense server requires the public key in the format ssh-rsa AAAAB3NC7we...wIfhtcSt== and is assigned to a specific user (under System/Access/Users) in the field 'Authorized keys'.

Client needs to support ssh-agent and accepts the private key in the format:

-----BEGIN RSA PRIVATE KEY-----
[BASE64 ENCODED DATA]
-----END RSA PRIVATE KEY-----

The command to add the private key to ssh-agent:

eval "$(ssh-agent -s)"  # Start the ssh-agent in the background
ssh-add id_rsa          # Add your SSH private key to the ssh-agent