NSH(8) System Manager's Manual NSH(8)

Name

nsh - network shell for OpenBSD routers

Description

NSH is a CLI intended for OpenBSD-based network appliances. It replaces ifconfig, sysctl and route with its own simple command language, and consolidates configuration for other daemons into one place, effectively replacing /etc/netstart and parts of /etc/rc for appliance-style usage.

NSH presents the user with a vaguely cisco-like interface with all configuration in one easy to read text list. It also gives the user access to system information and diagnostics. NSH replaces the userland commands which handle these functions, and talks directly to the OpenBSD kernel or control utility for daemon functionality.

Supported External Utilities

bgpd, dhcpd, dhcpleased, dhcrelay, dvmrpd, eigrpd, ftp-proxy, ifstated, inetd, iked, ipsecctl, ldapd, ldpd, npppd, ntpd, ospfd, ospf6d, pf, rad, relayd, resolvd, ripd, sasyncd, slaacd, smtpd, snmpd, sshd, tftpd, tftp-proxy.

Examples

$ nsh
> show interface status
em0 up   em1 up   vlan40 up   wg0 up
> show diff-config
no differences. as it should be.
> enable
privileged mode. be reasonable.

License

NSH is completely free, it only incorporates code with BSD-style licenses.

Status

Follow OpenBSD ports (shells/nsh) or the github repository for updates. NSH 1.2.1 is the latest release.

New in 1.2.1:

- disable interactive mode if -c or -i options are used
- fix a divide-by zero crash when reading commands from stdin
- start less(1) pager in restricted mode for the manual command
- fix build on OpenBSD-current
- improve nsh.8 accuracy and general syntax
- fix file locking error when loading of config examples is stopped with Ctrl-C
- release process improved and documented by stsp

New in 1.2:

- tab-completion improvements
- make autoconf4 work on pppoe interfaces
- add interface-context inet and inet6 commands
- add ipcp command which configures IPCP on pppoe interfaces
- require privileged mode for the configure command
- enable secret now performs some password sanity checks
- add show pf commands to display pf firewall status
- make some top-level commands available in interface/bridge context
- add show ip command which provides an overview of IP addresses
- add show active-config and show diff-config commands
- add umb(4) support
- call /sbin/reboot instead of reboot(2) syscall to ensure clean reboots
- use more(1) style input keys for the built-in pager
- make the enable command switch to the root user via doas.conf or root password
- add bgpnsh(8), a minimal version of nsh for use as a BGP looking-glass shell
- add show crontab, crontab edit, crontab install commands
- add show environment, setenv, unsetenv, and saveenv commands
- allow empty configuration files to be filled with data from /etc/examples
- allow nsh commands to be piped to standard input from another process
- add support for running a separate instance of dhcpd per routing domain
- add dhcp restart command

New in 1.1:

- mandoc format manual page
- configure is now part of the typical usage pattern
- show vlan command for a quick view of vlans
- show bridge command for a quick view of bridges
- show interface status command for a quick view of interfaces
- Wireguard support
- ndp support
- static arp interface support
- nameserver support through resolvd (replaces dns local-control)
- interface command mode now requires 'exit' or '..' or ^X to leave
- add several networking related sysctls
- slaacd support, including show autoconf
- dhcpleased support, replacing dhclient
- rc.d scripts
- rad replaces rtadvd
- rxprio/txprio for interfaces (incl. bridges)
- llpriority for interfaces
- eigrpd support
- pair/patch support
- more sensible isakmpd default flags
- show ipsec sadb and show ipsec flows for IPsec users
- pflow support
- Numerous bug fixes

Details

Check out examples for example NSH configurations.

- For detailed information, or if you want to help develop nsh, read the README, TODO and nsh.8 documents.
- Audio: BSDTalk 229 and PLUG 3/19/13 Slides: PLUG 3/19/13
- Video: Tom Smyth at EuroBSDCon 2022
- Video: Tom Smyth at BSDCan 2024

Development

- Mailing list for nsh (List archive)
- GitHub source repository, wiki, issue tracker
- At some point I accidentally merged flashrd and nsh trees on GitHub. We might clean that up when transitioning off github.

Download

- NSH v1.2.1
- latest nsh snapshot
- flashrd for installation of openbsd on flash

See Also

dqc(7), forge(1), nsh(8) manual

OpenBSD July 21, 2026 NSH(8)