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

nsh — network configuration shell

nsh [-v] [-i rcfile] [-c config-script-file]

nsh is a command interpreter intended for both interactive and shell script use. nsh is an alternative to: ifconfig(8), sysctl(8), route(8), and encapsulates configuration for other daemons into one place. nsh provides an alternative to: netstart(8) and parts of rc(8). nsh has its own command language similar to the configuration language used by many network appliance vendors.

nsh encapsulates the many available networking services and daemons that are included in OpenBSD base, see the SEE ALSO section for a complete list.

nsh is a shell to configure OpenBSD kernel's networking functions such as routing of packets, firewalling, network address translation, rate limiting, bandwidth queueing, LAN bridging, IP tunnelling, and encryption. nsh provides simple wrappers around these functions to aid setting up a network. The goals of this software are:

nsh encapsulates those configuration files, so that their native configuration files are encapsulated within the nsh configuration framework. nsh does not in any way obfuscate the configuration syntax that is utilised or provided by these ctl.c based programs. nsh allows the administrator to view and edit all configuration in one place.

When nsh is run without arguments it loads an interactive shell.

The options are as follows:

nsh produce verbose output
config-script-file
nsh execute the command(s) in the config-script-file. This is typically used to implement scripted changes to configuration.
rcfile
load the initial system configuration from the command(s) in the rcfile. This is typically used to clear the configuration and load a full nsh configuration script from rcfile .

When run without any command line arguments, nsh presents an unprivileged shell to the user. All nsh interactive command line modes allow basic command line editing features from editline(7) library. The command history of the current session is available through the up / down arrow keys.

It is possible to repeat the commands from the command history.

Any command can be abbreviated as long as the abbreviation is not ambiguous. e.g. 'show running-config' can be abbreviated to 'sho run'.

If the user enters a command that is ambiguous nsh warns the user with 'Ambiguous argument' message, e.g. ambiguous command entry.

nsh/show i
% Ambiguous argument i

nsh has double <Tab> command line completion for user convenience if the command is not ambiguous double <Tab> completes the command. If what is typed is ambiguous double tab presents the administrator with the available command line options that match what has been typed thus far.

  • E.g. command line completion display 
    nsh(p)/i
ifstate         inet            ip              ipsec
ike             interface       ip6

Use the up arrow on most keyboards to review the previous commands entered in the current session. The command being currently viewed can be repeated by hitting enter.

nsh commands can be reversed in the following ways:

  • Any affirmative commands that do not contain enable keyword can be reversed with the no keyword in front of the affirmative version of the command. e.g. reverse allowing IP packet forwarding. 
    nsh(p)/ip forwarding
nsh(p)/no ip forwarding
  • Any affirmative commands that contain enable keyword can be reversed with disable keyword. E.g reverse enabling packet filter firewall command. 
    nsh(p)/pf enable
%pf enabled
nsh(p)/pf disable
%pf disabled

nsh shell starts as an unprivileged prompt which displays as the text of the FQDN (fully qualified domain name) of the machine followed by a forward slash.

  • e.g. standard prompt of the device firewall.machine.com 
    firewall.machinename.com/
The privileged shell is accessed using the enable command. The privileged shell has the FQDN of the machine followed by (p) to indicate privileged and followed by a /
  • e.g. privileged shell prompt of the device firewall.machine.com 
    firewall.machinename.com(p)/

For the purposes of this manual, any examples the machine is called nsh

  • e.g. standard prompt appearing in examples in this manual 
    nsh/
  • e.g. privileged prompt appearing in examples in this manual 
    nsh(p)/

? | help [nsh-command]

Display available commands and options that can used in the current nsh mode. The help or ? can be followed by a nsh command, nsh displays the purpose of the specified command.

[hostname]

hostname without arguments displays the current configured hostname of the system. hostname with an argument will set hostname to the argument's value.

Start a privileged shell to allow the user run privleged configuration commands. i.e. enable privileged command shell mode. If an enable secret or password is set, the user shall be prompted to enter the password to access the privileged shell.

[no] enable secret

Set or the password that an administrator would enter to access the privileged shell.

Exit privileged mode. Useful if you have completed configuration but still want the ability to run diagnostics in an unprivileged nsh shell.

[no] rtable [table-id] [name]

rtable when used with a specified table-id can execute services, diagnostic commands (ping, traceroute) and set routes under alternate routing tables. The default OpenBSD kernel can accommodate 256 rtables. They have a 1:1 relationship with routing domains, except that routing domain 0 can contain multiple routing tables. In addition, routing tables initialized prior to their corresponding routing domain, shall be initialised with a routing domain of 0.

[no] group [group-name] [carpdemote] [demotion-counter]

Modify group attributes for the group-name named group. TBC

[no] arp [IPv4-Address] [MAC-Address]

Set or remove a static IP address and MAC address binding for Address Resolution Protocol. TBC

[no] bridge [bridge-name]

Modify bridge configuraiton on the named bridge. See also OpenBSD manual pages for bridge(4) and ifconfig(8) (accessible via the following nsh commands):

!man bridge
!man ifconfig
nsh(p)/bridge bridge1
nsh(bridge-bridge1)/?
% Commands may be abbreviated.
% Press enter at a prompt to leave bridge configuration mode.
% Bridge configuration commands are:

  description   Bridge description
  member        Bridge member(s)
  span          Bridge spanning port(s)
  blocknonip    Block non-IP traffic forwarding on member(s)
  discover      Mark member(s) as discovery port(s)
  learning      Mark member(s) as learning port(s)
  stp           Enable 802.1D spanning tree protocol on member(s)
  maxaddr       Maximum address cache size
  timeout       Address cache timeout
  maxage        Time for 802.1D configuration to remain valid
  fwddelay      Time before bridge begins forwarding packets
  hellotime     802.1D configuration packet broadcast interval
  priority      Spanning priority for all members on an 802.1D bridge
  rule          Bridge layer 2 filtering rules
  static        Static bridge address entry
  ifpriority    Spanning priority of a member on an 802.1D bridge
  ifcost        Spanning tree path cost of a member on 802.1D bridge
  link          Link level options
  txprio        Priority in tunnel protocol headers
  rxprio        Source used for packet priority
  vnetid        Virtual interface network identifier
  parent        Parent interface
  tunneldomain  Tunnel parameters
  shutdown      Shutdown bridge
  ?             Options
[no] ip6 [? | forwarding | mforwarding | multipath | maxifprefixes | maxifdefrouters | maxdynroutes]

Configure IPv6 networking parameters, such as forwarding, multicast forwarding, multipath routing, etc.

[no] ip6 forwarding

Enable or disable forwarding (routing /NAT) of IPv6 packets through the kernel.

nsh(p)/ip6 forwarding

[no] ip6 forwarding

Enable or disable forwarding of IPv6 multicast packets through the kernel.

nsh(p)/ip6 mforwarding

[no] ip6 multipath

Enable or disable multipath routing for IPv6 addresses. If multipath is disabled, only the first selected route is used for a given destination regardless of how many routes exist in the routing table.

nsh(p)/ip6 multipath

[no] ip6 maxdynroutes [max-route-value]

Set or disable the limit on maximum number of IPv6 routes created as a result of incomming ICMPv6 redirects. The max-route-value can be set to any value 0-20480 or -1. A value of 0 prevents any routes being created as a result of incoming ICMPv6 redirects. Set to -1 to disable the limit. The default value for maxdynroutes is 4096.

nsh(p)/ip6 maxdynroutes 8192
[no] mpls [? | ttl | mapttl-ip | mapttl-ip6] Configure MPLS (Multi Protocol Label Switching) network parameters in the kernel. 
nsh(p)/mpls ?
% Commands may be abbreviated.
% 'mpls' commands are:

  ttl         MPLS ttl
  mapttl-ip   MPLS mapttl IPv4
  mapttl-ip6  MPLS mapttl IPv6
  ?           Help

[no] mpls ttl [0-255]

Configure the default MPLS (Multi Protocol Label Switching) TTL (time to live) in the kernel for MPLS shim headers of generated (not forwarded) MPLS packets. The default value is 255.

nsh(p)/mpls ttl 64

[no] mpls mapttl-ip [0-1]

Set or unset whether the kernel decrements the TTL of the IP packet header that is encapsulated in mpls packet, when the packet is mpls label switched (forwarded via MPLS). This is useful when diagnosing failures in the forwarding path of an MPLS tunnel. If set to 0, the encapsulated payload IP header TTL is not modified while passing through MPLS and the MPLS label stack. The default value is 1.

nsh(p)/mpls mapttl-ip 1

[no] mpls mapttl-ip6 [0-1]

Set or unset whether or not the kernel decrements the TTL of the IPv6 packet header that is encapsulated in mpls packet, when the packet is mpls label switched (forwarded via MPLS). This feature is useful when diagnosing failures in the forwarding path of an MPLS tunnel. If set to 0, the encapsulated payload IPv6 header TTL field is not modified while passing through MPLS and the MPLS label stack. The default value is 0.

nsh(p)/mpls mapttl-ip6 1

[no] ddb [? | panic | console | log]

Configure or remove kernel debug (DDB) options.

nsh(p)/ddb ?
% Commands may be abbreviated.
% 'ddb' commands are:

  panic    DDB panic
  console  DDB console
  log      DDB log
  ?        Help

[no] ddb panic

Enable or disable dropping the system to the kernel debugger in the event of a system panic. By default, dropping to the ddb debugger in a system panic is enabled.

nsh(p)/ddb panic

[no] ddb console

Enable access to the kernel debugger from the console using an architecture-dependent magic key sequence on the console or a debugger button. When running OpenBSD with a securelevel(7) greater than 0, this feature cannot be enabled. By default accessing the ddb debugger from the console is disabled.

nsh(p)/ddb console

[no] ddb log

Enable or disable logging the output of the kernel debugger in the kernel message buffer. By default ddb debugger output logging to the kernel message buffer is enabled.

nsh(p)/ddb log

[no] pipex [? | enable]

Enable or disable pipex(4) processing on pppac(4) and pppx(4) interfaces. pipex(4) handles PPP frames and forwards IP packets in-kernel. It accelerates the performance of packet forwarding, because it reduces copying of packets between kernel and userland. By default pipex is disabled.

nsh(p)/pipex enable
[? | enable | disable | edit | reload]

Control the configuration and operation of the pf (Packet Filter) firewall.

nsh(p)/pf ?
% Arguments may be abbreviated

   enable  enable service
   disable disable service
   edit    edit configuration
   reload  reload service

pf edit

Open the default system editor and edit the firewall configuration. The edited ruleset is automatically validated on saving and exiting the editor. Note! firewall configuration changes DO NOT take effect until the "pf reload" command is entered. The editor used by nsh can be customised to your preferred editor using the EDITOR and VISUAL environment variables. For packet filter configuration syntax, refer to pf.conf(5).

nsh(p)/!man pf.conf
nsh(p)/pf edit

pf reload Once the pf ruleset has been edited and validated the modified pf configuration can be applied with this command.

nsh(p)/pf reload
[? | enable | disable | edit | reload | fib | log] Enable, disable or configure ospfd(8), the OSPF (Open Shortest Path First) daemon. 
nsh(p)/ospf enable

ospf edit Edit the configuration of the OSPF daemon. The edited ruleset is automatically validated on saving and exiting the editor. Note ospfd configuration changes DO NOT take effect until the "ospf reload" command is entered. The editor used by nsh can be customised to your preferred editor using the EDITOR and VISUAL environment variables. For OSPF configuration syntax, refer to ospfd.conf(5).

nsh(p)/!man ospfd.conf
nsh(p)/ospf edit

ospf reload Reread and apply the OSPF configuration.

nsh(p)/ospf reload

ospf fib [? | couple | decouple | reload]

Configure whether or not ospfd(8) updates the forwarding information base (the active kernel routing tables). The decouple feature is useful for monitoring OSPF networks without affecting the routing table of the system. OSPF decouple should only be done where there is only one link between the system and the rest of the OSPF network. The ospf fib reload command re fetches and relearns the routes in the FIB and passes them to the ospfd daemon for processing.

nsh(p)/ospf fib decouple

ospf log [? | verbose | brief]

Configure the detail level of ospfd(8) logging messages. Set ospf log verbose to enable detailed debug log output from ospfd. set ospf log brief to disable detailed debug log output from ospfd.

nsh(p)/ospf log verbose

[? | enable | disable | edit] [options]

Enable or disable or configure the eigrpd(8) Enhanced Interior Gateway Routing Protocol daemon. The configuration of eigrp daemon can be edited with edit command, the configuration syntax of eigrp daemon is documented in eigrpd.conf(5) manual page. Thre are a number of options that can be used to control the operation of eigrpd(8) daemon, these options are documented in the eigrpctl(8) manual page.

[? | enable | disable | edit] [options]

Enable or disable or configure bgpd(8), the Border Gateway Protocol daemon. Configuration of the bgp daemon can be edited with edit command, the syntax is documented in bgpd.conf(5). Thre are a number of options that can be used to control the operation of bgpd(8), documented in bgpctl(8).

[? | enable | disable | edit] [options]

Enable or disable or configure the ripd(8) Routing Information Protocol daemon. The configuration of rip daemon can be edited with edit command, the configuration syntax is documented in ripd.conf(5). Thre are a number of options that can be used to control the operation of ripd(8) daemon, these options are documented in ripctl(8).

[? | enable | disable | edit] [options]

Enable or disable or configure the ldpd(8) Label Distribution Protocol daemon. The configuration of ldp daemon can be edited with edit command, the configuration syntax of ldp daemon is documented in ldpd.conf(5). Thre are a number of options that can be used to control the operation of ldpd(8) daemon, these options are documented in ldpctl(8).

[? | enable | disable | edit] [options]

Enable or disable or configure the relayd(8), a load balancer and TLS termination daemon. The configuration of relay daemon can be edited with edit command, the syntax is documented in relayd.conf(5). There are a number of options that can be used to control the operation of relayd(8) daemon, these options are documented in relayctl(8).

[? | enable | disable | edit | reload]

Enable or disable or configure the isakmpd(8) Internet Key Exchange version 1 IKEv1 ISAKMP / Oakley daemon. The configuration of ipsec daemon can be edited with edit command, the configuration syntax of ipsec daemon is documented in isakmpd.conf(5) and ipsec.conf(5).

[? | enable | disable | edit] [options]

Enable or disable or configure the iked(8) Internet Key Exchange version 2 IKEv2 daemon. The configuration of ike daemon can be edited with edit command, the configuration syntax of ike daemon is documented in iked.conf(5). options to control the iked(8) daemon in a similar manner to ikectl(8) i.e to force ike daemon to run in active mode or passive mode, or reload the the daemon configuration. These features are documented in ikectl(8).

[? | enable | disable | edit]

Enable or disable or configure the dvmrpd(8) Distance Vector Multicast Routing Protocol daemon. The configuration of dvmrp daemon can be edited with edit command, the configuration syntax of dvmrp daemon is documented in dvmrpd.conf(5) manual page.

[? | enable | disable | edit]

Enable or disable or configure the rad(8) Router Advertisement daemon for IPv6. The configuration of rad daemon can be edited with edit command, the syntax is documented in rad.conf(5).

[? | enable | disable | edit]

Enable or disable or configure the sasyncd(8) IPSec Security Association synchronisation daemon for failover gateways. The configuration of sasync daemon can be edited with edit command, the configuration syntax of sasync daemon is documented in sasyncd.conf(5).

[? | enable | disable | edit]

Enable or disable or configure the dhcpd(8) Dynamic Host Configuration Protocol daemon. The configuration of dhcp daemon can be edited with edit command, the configuration syntax of dhcp daemon is documented in dhcpd.conf(5).

[? | enable | disable | edit | trap] [options]

Enable or disable or configure the snmpd(8) Lightweight Directory Access Protocol daemon. The configuration of snmp daemon can be edited with edit command, the configuration syntax of snmp daemon is documented in snmpd.conf(5).

[? | enable | disable | edit] [options]

Enable or disable or configure the ldapd(8) Lightweight Directory Access Protocol daemon. The configuration of ldap daemon can be edited with edit command, the configuration syntax of ldap daemon is documented in ldapd.conf(5). options to control the ldapd(8) daemon in a similar manner to ldapctl(8) e.g. to set log verbose vs brief or to compact / re-index the LDAP database are documented in ldapctl(8).

[? | enable | disable | edit] [options]

Enable or disable or configure the smtpd(8) OpenSMTPD Simple Mail Transfer Protocol daemon. The configuration of smtp daemon can be edited with edit command, the configuration syntax of smtp daemon is documented in smtpd.conf(5) manual page.

options to control smtpd(8) in a similar manner to smtpctl(8) i.e pausing / resuming mta (mail transfer agents) / mda (mail delivery agents) are documented in smtpctl(8).

[? | enable | disable | edit]

Enable or disable or configure the sshd(8) OpenSSH secure shell daemon. The configuration of sshd daemon can be edited with edit command, the syntax is documented in sshd_config(5).

[enable | disable | edit]

Enable or disable or configure the ntpd(8) Open network time protocol daemon. The configuration of ntp daemon can be edited with edit command, the syntax is documented in ntpd.conf(5).

[? | enable | disable | session | monitor | edit] [clear ? | all | ppp-id | address | interface | protocol | realm | username] [session ? |all | brief | packets] [monitor ? | all | ppp-id | address | interface | protocol | realm | username]

Enable or disable or configure the npppd(8) new Point-to-Point Protocol daemon. The nppp daemon supports termination of PPPoE, PPTP and L2TP PPP tunnels. npppd(8) works with pipex(4) for improved throughput through the ppp tunnels.

The configuration of nppp daemon can be edited with edit command, the syntax is documented in npppd.conf(5).

[enable | disable | edit]

Enable or disable or configure the ifstated(8) interface state daemon. The configuration of ifstate daemon can be edited with edit command, the syntax is documented in ifstated.conf(5).

[enable | disable] Activate or deactivate the local ftp proxy on the system. ftp-proxy in order to function properly requires pf to be enabled on the system. nsh starts ftp-proxy on 127.0.0.1 (rdomain 0) by default. Redirect rules in pf must be used to direct outside traffic from any rdomain to the local tftp daemon.

[enable | disable]

Activate or deactivate the local tftp proxy on the system. tftp-proxy in order to function properly requires pf to be enabled on the system. nsh starts tftp-proxy on 127.0.0.1 (domain 0), port 6969 by default. Redirect rules in pf must be used to direct outside traffic from any rdomain to the local tftp proxy.

[enable | disable]

Enable or disable the tftp daemon. nsh starts tftpd on 127.0.0.1, port 69 by default.

[local-control | dhcp-control | edit]

Configure Domain Name Service client on the system. local-control is for manual statically configured DNS client setup. dhcp-control is to allow dhcp client to update DNS client settings from recieved DNS servers in a DHCP offer. edit command, is used to statically configure DNS options, the syntax is documented in resolv.conf(5).

[enable | disable | edit]

Enable or disable or configure the inetd(8) inet superserver daemon. The configuration of inet daemon can be edited with edit command, the syntax is documented in inetd.conf(8).

[options] host

Send ICMP ECHO_REQUEST packets to an IPv4 network host, specified by name or IPv4 address. The options are documented in the ping(8).

[options] host

Send ICMP ECHO_REQUEST packets to an IPv6 network host, specified by name or IPv6 address. The options are documented in the ping6(8) manual page.

[options] host

Trace and print the route packets take to an IPv4 network host, specified by name or IP address. The options are documented in traceroute(8).

[options] host

Trace and print the route packets take to an IPv6 network host, specified by name or IP address. The options are documented in traceroute6(8).

[options] [-p port] host

Open a OpenSSH ssh(1) session to the remote system host, specified by name or IP address. The port is the TCP port on the remote host which you wish to connect. The options are documented in ssh(1).

[options] [host] [port]

Open a telnet(1) session to the given TCP port on the remote server host, specified by name or IP address. If the port is not specified the IANA assigned port 23 for telnet will be used. The options are documented in telnet(1).

Restart the system. Warning no confirmation prompt is issued, configuration changes are NOT automatically saved! User must save configuration manually BEFORE using reboot. Requires privileged access.

shut down the system. Warning no confirmation prompt is issued, configuration changes are NOT automatically saved! User must save configuration manually BEFORE using halt. Requires privileged mode.

Save the running configuration to the permanent configuration space. On the next startup of the system, this saved configuration is used.

[no] verbose

Verbose mode sets nsh to display extra information on entered commands. It is useful during a diagnostic and troubleshooting session.

[hostname | interface | route | route6 | sadb | arp | kernel | bgp | ospf | ospf6 |eigrp | rip | ldp | ike | ipsec | dvmrp | relay | dhcp | smtp | ldap | monitor | version | users | running-config | startup-config |? | help]

The main diagnostic and informational command is 'show'. show without arguments displays the available diagnostic show sub commands.

show hostname

Display the system's currently assigned hostname.

show interface [interface-name]

Display essential information about the system network interfaces including any network bridges / switches. show interface without any arguments displays information about all interfaces available on the system.

show interface interface-name Display information about a specific interface.

show route

Display a dump of the kernel routing table, including ARP entries.

e.g. display contents of the routing table.

nsh/show route
Flags: U - up, G - gateway, H - host, L - link layer, R - reject (unreachable),
       D - dynamic, S - static

% IPv4 routing table:

Destination        Gateway            Flags     Refs  Packets    Mtu  Interface
0.0.0.0/0          172.20.1.1         UGS         3     57502      -   sis0
127.0.0.0/8        127.0.0.1          UGRS        0         0  33224   lo0
127.0.0.1          127.0.0.1          UH          2        12  33224   lo0
172.20.1.0/24      link#1             U           0         0      -   sis0
172.20.1.1         8:0:20:71:22:e7    UHL         1         0      -   sis0
172.20.1.2         127.0.0.1          UGHS        0         0  33224   lo0
172.20.1.23        link#1             UHL         1      1764      -   sis0
172.20.1.255       link#1             UHL         2      1555      -   sis0
224.0.0.0/4        127.0.0.1          URS         0         0  33224   lo0

show monitor

start an interactive console monitor mode for the system's routing socket. The monitor displays raw descriptions of the data passing into the kernel's routing socket and dumps of the kernel's routing messages to the machine. Press enter or control-C to exit this mode.

show version

This displays basic information about the host and about NSH, such as the version of NSH installed, the system's uptime and kernel version. It also shows both the kernel that NSH was compiled under, and the current kernel that NSH is running under. nsh should always be running on a kernel that is of a similar version to the version of the kernel/header files that NSH was compiled under. This ensures that nsh can interact with the kernel properly (and vice versa).

nsh/show version
% NSH v1.0
Compiled 03-Apr-22 06:03 by _pbuild@amd64-1.ports.openbsd.org
uptime: 1 day, 2 hours, 17 minutes
system: OpenBSD/amd64 version 7.1
cpu: Intel(R) Core(TM) i7-10610U CPU @ 1.80GHz
memory: 8175MB
kernel: OpenBSD 7.1 (GENERIC.MP) #459: Mon Apr  4 18:16:13 MDT 2022
    deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/GENERIC.MP

show running-config

Display the current running configuration on the system, including interface and bridge configurations, routes, the system hostname, firewall rules, and other information compiled by nsh.

show startup-config

Display the startup configuration on the system, read from nshrc, including interface and bridge configuration, routes, the system hostname, firewall rules, and other information compiled by nsh TBC [routes | arp | line | bridge-dyn | bridge-all | bridge-rule | pf | history |? | help]

Clear various system tables.

flush routes

Clear the system routing table.

flush arp

Clear the system arp cache and static arp table.

flush bridge-dyn bridge-name

Clear dynamically learned members from the named bridge.

nsh/flush bridge-dyn bridge0

Delete all dynamically learned members from bridge0. Note! any members set manually (static members) are not removed by this command.

flush bridge-all bridge-name

Clear dynamically and statically learned members from the named bridge.

nsh/flush bridge-all bridge0

flush bridge-rule bridge-name interface-name

Clear all rules on the named bridge on the named interface.

nsh/flush bridge-rule bridge0 vether0

flush history

Clear the command history

[no] route [destination] [/prefixlen | netmask] gateway [flags]

Add or remove static routes. IPv4 addresses can be configured with prefix length in CIDR or dotted decimal IP netmasks (e.g. 255.255.255.0) to describe the route. The IPv6 address may only be configured with a prefix length. This command only runs in privileged mode.

Flags: blackhole | cloning | iface | llinfo | nmpath | nostatic | proto1 | proto2 | reject [mtu mtu-bytes] [expire seconds]

blackhole	RTF_BLACKHOLE	discard packets for this route
cloning		RTF_CLONING	generate a new route on use
iface		!RTF_GATEWAY	destination is directly reachable
llinfo		RTF_LLINFO	translates proto addr(l3) to link addr(l2)
nompath		!RTF_MPATH	do not allow multiple gateways for this route
nostatic	!RTF_STATIC	do not save this in the static routing table
proto1		RTF_PROTO1	protocol specific flag #1
proto2		RTF_PROTO2	protocol specific flag #2
reject		RTF_REJECT	reject packets with ICMP unreachable

exit nsh

[no] verbose

Sets verbose mode on / off. (By default verbose mode is off). Use the no keyword turn verbose mode off.

nsh(p)/verbose
% Diagnostic mode enabled

nsh(p)/no verbose
% Diagnostic mode disabled

[no] editing

Set command line editing on / off. (If defaults to on). Use the no keyword to turn command editing mode off.

nsh(p)/editing
% Command line editing enabled

nsh(p)/no editing
% Command line editing disabled

[shell-command] argument-1 [argument-n]

Invoke a shell or run an entered shell-command with arguments if required. (requires privileged mode). The active users login shell is the shell that is invoked by this feature. This feature disabled to enhance security.

E.g. list files in /root

nsh(p)/!ls /root

helloworld.c
helloworld2.c

nsh(p)/!

OpenBSDshell#

[no] ip [arptimeout | arpdown | carp | carp-log | carp-preempt | forwarding | mforwarding | mtu-path-disc | mtu-disc-timeout | ipip | gre | wccp | etherip | ipcomp | esp | esp-udpencap | esp-udpencap-port | ah | sourceroute | encdebug | send-redirects | ifq-maxlen | directed-broadcast | multipath | default-ttl |?]

Modify system kernel ip processing parameters or features. (requires privileged mode).

All commands in this category allow the 'no' modifier to disable the option.

nsh(p)/ip ?
% Commands may be abbreviated.
% 'ip' commands are:

  arptimeout          Seconds for ARP entries to remain in cache
  arpdown             Seconds before resending unanswered ARP requests
  carp                Allow CARP
  carp-log            CARP Logging Priority
  carp-preempt        CARP Virtual Host Preemption
  forwarding          Enable IPv4 Forwarding
  mforwarding         Enable IPv4 Multicast Forwarding
  mtu-path-disc       Enable IPv4 MTU Path Discovery
  mtu-disc-timeout    Seconds that MTU entries remain in Path MTU discovery cache
  ipip                Allow IP-in-IP Encapsulation
  gre                 Allow Generic Route Encapsulation
  wccp                Allow Web Cache Control Protocol
  etherip             Allow Ether-IP Encapsulation
  ipcomp              Allow IP Compression
  esp                 Allow Encapsulated Security Payload
  esp-udpencap        Allow ESP encapsulation within UDP
  esp-udpencap-port   UDP port number for encapsulation
  ah                  Allow Authentication Header
  sourceroute         Process Loose/Strict Source Route Options
  encdebug            Enable if_enc debugging
  send-redirects      Send ICMP redirects
  ifq-maxlen          IPv4 ifqueue max length
  directed-broadcast  Allow directed broadcasts
  multipath           Multipath routing
  default-ttl         Default IP packet TTL
  ?                   Options
ip arptimeout seconds

Sets the timeout (seconds) for ARP entries to remain in cache on this system.

When the system stops receiving ARP packets from the host and, the arptimout seconds pass, the arp entries are removed from the ARP cache. If a service or user requests to communicate with the IP address of the removed cache entry the system requests via broadcast an ARP request. Lower arptimeout values increase the broadcast traffic on the underlying network. While higher arptimeout values increase the time it takes to resolve a host. This setting should be the same or lower on a router than the bridge MAC table timeout on an intermediate bridge.

nsh(p)/ip arptimeout 300

[no] ip arpdown seconds

Set or remove configured timeout (seconds) the system waits before resending an unanswered ARP request.

If the ARP system fails to resolve a MAC address, the system waits for ip arpdown number of seconds before retrying.

Lower settings increases the broadcast traffic on the underlying network while higher settings increases the time it takes to resolve a host (after the host boots up) and on a network that is experiencing packet loss.

nsh(p)/ip arpdown 20

[no] ip carp

Enable or disable carp(4) functionality in the system kernel. Carp is a BSD licensed technology for router redundancy utilising a virtual ip that floats between 2 or more routers on a LAN segment, it is similar to VRRP or HSRP.

nsh(p)/ip carp

[no] ip carp-log 0-7

Enable or disable logging of carp state change, bad packets and other errors in the system kernel. carp-log may be set to a value between 0 and 7 corresponding with standard syslog(3) priorities. The default value is 2, which limits logging to changes in CARP state.

nsh(p)/ip carp-log 7

[no] ip carp-preempt

Enable or disable the device taking master role from an existing master carp router

nsh(p)/ip carp-preempt

[no] ip forwarding

Enable or disable IP packet forwarding in the system kernel. This must be set in order to use routing, NAT, IPsec or packet filter features.

nsh(p)/ip forwarding

[no] ip ipip

Enable or disable IP-in-IP encapsulation in the system kernel.

nsh(p)/ip ipip

[no] ip gre

Enable or disable Generic Route Encapsulation in the system kernel. Must be used to enable gre(4) interfaces.

nsh(p)/ip gre

[no] ip wccp

Enable or disable GRE-based Web Cache Control Protocol packets to manage caching device. Must be used to enable WCCP on gre(4) interfaces.

nsh(p)/ip wccp

[no] ip etherip

Enable or disable GRE-based Ether-IP encapsulation in the system kernel.

nsh(p)/ip etherip

[no] ip ipcomp

Enable or disable IPComp internet protocol compression in the system kernel.

nsh(p)/ip ipcomp

[no] ip esp

Enable or disable IPsec Encapsulated Security Payload procesing in the system kernel. (Enabled by default.)

nsh(p)/ip esp

[no] ip esp-udpencap Enable or Disable processing of UDP encapsulated ESP packets in the system kernel. (Enabled by default.)

nsh(p)/ip esp-udpencap

[no] ip esp-udpencap-port 0-65535 Sets the value of the UDP port that triggers decapsulation for incoming UDP encapsulated ESP packets. (The default port is 4500) udp encapsulated esp packets are useful for traversing NAT routers.

nsh(p)/ip esp-udpencap-port 4600

[no] ip ah

Enable or disable IPsec Authentication Header processing in the system kernel. (Enabled by default.)

nsh (p)/ip ah

[no] ip sourceroute

Enable or disable processing loose or strict source routing options on IP packet headers. Do not enable this option on systems connected to the public internet.

nsh(p)/ip sourceroute

[no] ip encdebug

Enable or disable printing debug messages for the enc(4) interface to the kernel output. Note! Requires a kernel compiled with ENCDEBUG option.

nsh(p)/ip encdebug

[no] ip send-redirects

Controls whether or not the system sends ICMP redirects to local hosts. (Enabled by default).

When there is a direct path on the local network from one host to another, but one of those hosts chooses to talk through the router instead, the system sends an ICMP redirect to the originating host. This redirect tells the host the direct path on the network to send further packets.

nsh(p)/ip send-redirects

[no] ip directed-broadcast

Enable or disable kernel forwarding of IP traffic to the broadcast address of any interface on the system. This setting is useful for limiting certain types of DoS attacks.

[no] ip multipath

Enable or disable ip multicast forwarding in the system kernel. (Disabled by default.)

nsh(p)/ip mforwarding

[no] ip default-ttl ttl

Sets the default ttl used on IP packets originating from this system. Valid ttl value is in the range 1-255.

The TTL, or time-to-live, is decremented by one each time the packet passes through another router on the internet. The default TTL that the system uses is 64, therefore it allows for the packet to pass through up to 64 routers (also called hops) before reaching its destination. The main purpose of the TTL is to avoid routing loops in the network.

nsh(p)/ip default-ttl 128

ip ?

Displays the help menu and available ip command options.

nsh(p)/ip ?
[no] interface [ip | alias | description | group | rdomain | rtlabel | priority | llpriority | mtu | metric | link | arp | lladdr | nwid | nwkey | powersave | txpower | bssid | media | mediaopt | auth | peer | pppoe | tunnel | tunneldomain | txprio | rxprio | vnetid | vnetflowid | parent | patch | keepalive | mplslabel | pwe | syncdev | syncpeer | maxupd | vhid | advbase | advskew | carppass | carpdev | carpnode | carppeer | balancing | pflow | debug | dhcrelay | wol | mpls | inet6 | autoconf6 | autoconfprivacy | temporary | monitor | wgpeer | wgport | wgkey | wgrtable | trunkport | trunkproto | shutdown |?] interface mode commands, are commands that can be applied to a specific named interface. 
nsh(interface-em0)/?
% Commands may be abbreviated.
% Press enter at a prompt to leave interface configuration mode.
% Interface configuration commands are:

  ip               IP address and other parameters
  alias            Additional IP addresses and other parameters
  description      Interface description
  group            Interface group
  rdomain          Interface routing domain
  rtlabel          Interface route labels
  priority         Data packet priority
  llpriority       Link Level packet priority
  mtu              Maximum Transmission Unit
  metric           Routing metric
  link             Link level options
  arp              Address Resolution Protocol
  lladdr           Link Level (MAC) Address
  nwid             802.11 network ID
  nwkey            802.11 network key
  powersave        802.11 powersaving mode
  txpower          802.11 transmit power
  bssid            802.11 bss id
  media            Media type
  mediaopt         Media options
  auth             PPP authentication
  peer             PPP peer authentication
  pppoe            PPPoE settings
  tunnel           Tunnel parameters
  tunneldomain     Tunnel routing domain for transit
  txprio           Priority in tunnel protocol headers
  rxprio           Source used for packet priority
  vnetid           Virtual interface network identifier
  vnetflowid       Use part of vnetid as flowid
  parent           Parent interface
  patch            Pair interface
  keepalive        GRE tunnel keepalive
  mplslabel        MPLS local label
  pwe              MPLS PWE3
  syncdev          PFsync control message interface
  syncpeer         PFsync peer address
  maxupd           PFsync max updates, defer first packet
  vhid             CARP virtual host ID
  advbase          CARP advertisement interval
  advskew          CARP advertisement skew
  carppass         CARP passphrase
  carpdev          CARP device
  carpnode         CARP additional vhid/advskew
  carppeer         CARP peer
  balancing        CARP balancing mode
  pflow            pflow data export
  debug            Driver dependent debugging
  dhcrelay         DHCP Relay Agent
  wol              Wake On LAN
  mpls             MPLS
  inet6            IPv6
  autoconf6        IPv6 Autoconfigurable address
  autoconfprivacy  Privacy addresses for IPv6 autoconf
  temporary        Temporary addresses for IPv6 autoconf
  monitor          Monitor mode for incoming traffic
  wgpeer           Wireguard peer config
  wgport           Wireguard UDP port
  wgkey            Wireguard private key
  wgrtable         Wireguard routing table
  trunkport        Add child interface(s) to trunk
  trunkproto       Define trunkproto
  shutdown         Shutdown interface
  ?                Options

[no] ip [dhcp] | address/prefix-length | address/netmask

Adds or removes the main IP address and other related parameters on the interface. IPv4 addresses can be configured with CIDR bitlength, or classic netmask. The IPv6 address may only be configured with a bitlength.

nsh(interface-lo0)/ip ::1/128
or 
nsh(interface-fxp0)/ip 192.168.100.1/24
or 
nsh(interface-fxp0)/ip 192.168.100.1/255.255.255.0

[no] alias address/prefix-length | address/netmask

Deprecated, adds or removes additional IP address and other related parameters on the interface. IPv4 addresses can be configured with CIDR bitlength, or classic netmask. The IP address may only be configured with a bitlength.

[no] ip dhcp

Enables or disables dhclient on a given (broadcast and layer2 capable) interface.

DHCP client notes: DHCP client mode takes control of default gateway route. There is currently no way to control default gateway if DHCP client is used on multiple interfaces. The first DHCP client interface to succeed in obtaining a lease sets the default gateway.

If /var/db is kept across reboots, (such as in a configuration where nsh is used on a hard disk) /var/db/dhclient.leasees.$if files may exist where not desired. The presence of /var/db/dhclient.leases.$if (where $if is the interface name) triggers DHCP mode to be turned on in saved nsh configurations (write) and in displayed nsh configurations (show running-config). If you are using nsh on a system where /var is kept persistently, look at the running configuration and execute 'no ip dhcp' for insterfaces on which you do not intend to use DHCP.

nsh(interface-fxp0)/ip dhcp

[no] description text

Adds or removes a descriptive label to the interface.

nsh(interface-em0)/description Chris-WAN01-Link

[no] group group-name [another-group-name...groupname-N]

Adds or removes a group label to the interface. The group can then be referred to in other configuration such as the firewall pf configuration. This is useful for grouping similar interfaces together and, can reduce the size of your firewall rule set. An interface can be a member of multiple groups.

nsh(interface-em0)/group WAN

[no] rdomain routing-domain-number

Sets the routing domain of an interface. Note that this command clears all existing ip configuration on the interface.

[no] rtlabel [rtable-id]

TODO Set or remove the rtable id on an interface. TODO better explanation needed!

[no] priority 0-15

Set the interface routing priority to a value in the range of 0 to 15 with smaller numbers being better. The default priority of an interface is 0, except for IEEE 802.11 wireless interfaces (priority 4), umb(4) interfaces (priority 6), and carp(4) interfaces (priority 15). The default priority of newly connected routes (routes created by configuring an IP address on an interface) is calculated by adding 4 (RTP_CONNECTED) to the interface priority. The default priority of new static routes added to the kernel is calculated by adding 8 (RTP_STATIC) to the interface priority.

[no] llpriority 0-7 Sets or remove the priority for link layer communications on the interface to a value between 0-7 (arp (4), bpf(4), pppoe(4).

nsh(interface-em0)/llpriority 7

[no] mtu mtu-bytes

Add or remove a configured Maximum Transmission Unit (MTU) on the interface. This is the maximum packet size that the operating system is permitted to transmit. Use the no keyword to set mtu to reset the interface MTU to the default value for that interface type.

The output of 'show interface' displays a 'hardmtu' value which is the maximum mtu value supported by the hardware and driver currently installed. The mtu command fails gracefully if the specified mtu exceeds the hardmtu value of the interface.

A larger MTU is particularly useful for underlay interfaces which encapsulated tunneled traffic traverses or for features which stack tags, such as PPPoE, MPLS tagging and QinQ (svlan) tagging.

nsh(interface-vr0)/mtu 1600

[no] metric 0-2147483647

Set routing metric for the interface. Using no keyword before metric sets the interface metric to the default value of zero.

nsh(interface-fxp0)/metric 2

[no] link <0|1|2>

Set any of the link flags on the interface. Using no keyword before link XYZ removes the specified link flags 'XYZ'. Using no keyword before link removes all link flags from the interface.

nsh(interface-gre0)/no link 0
Each different interface type uses link flags for different purposes.

[no] arp

Enable or disable Address Resolution Protocol ARP on the interface. (Enabled by default.)

nsh(interface-fxp0)/arp
nsh(interface-fxp0)/no arp

[no] lladdr mac-address | random

Set or remove the mac address on the interface. The administrator can specific a macadress in colon notation e.g. 00:11:22:33:44:55 or random to request a random mac address assignment for the interface.

nsh(interface-vether3)/lladdr random
nsh(interface-vether3)/lladdr 00:11:22:33:44:55

[no] nwid network-id

Set or remove the configured network ID for an 802.11 capable interface. Use the no keyword before the nwid to reset to the default value of a blank network ID.

[no] nwkey key

Set the WEP network key for an 802.11 capable interface. Use the no keyword before nwkey to turn off WEP.

[no] powersave time

Set the 802.11 powersaving mode to X ms of time. Use the no keyword before powersave to set the powersave mode to the default powersave time.

[no] txpower dBm

Set the transmit power on an 802.11 radio network interface manually. Power units are in dBm. Use the no keyword before txpower to set the radio transmit power to automatic.

E.g to set the tx power of iwn0 to 10dBm simply enter the command below:

nsh(interface-iwn0)/txpower 10

[no] bssid mac-address

Set or remove the configured BSSID of a radio interface to a specific MAC address, the mac-address should be entered in semi colon format e.g. 12:34:56:78:9a:bc.

E.g. set the bssid of radio interface iwn0

nsh(interface-iwn0)/bssid 12:34:56:78:90:12

[no] media [type] [instance]

Set the media type of the interface. Entering media without an argument diplays help for the media settings available for the interface.

E.g. show media settings supported by an intel pro 1000 em(4) interface

nsh(interface-em0)media

%autoselect | 10baseT | 100baseTx | 1000baseT.

E.g to set the speed of the network interface speed to 1000mb/s

nsh(interface-em0)/media 1000baseT
Note! Enabling verbose mode and running show interface <interfacename> displays all media settings supported by the network interface. 
nsh(p)/verbose
% Diagnostic mode enabled

nsh(p)/sho int vr0
% vr0
  Interface is up (last change 37d 12:16:02), protocol is up
  Interface type Ethernet (Broadcast), hardware address 00:0d:b9:29:6b:50
  Media type autoselect (100baseTX full-duplex), status active
  Internet address 100.64.0.1/24, fe80::20d:b9ff:fe29:6b50%vr0/64
  Routing Domain 0, MTU 1500 bytes (hardmtu 1740), Line Rate 100 Mbps
  187081496 packets input, 232860544316 bytes, 19 errors, 0 drops
  102231197 packets output, 21564487790 bytes, 0 errors, 3267264 unsupported
  1244 input, 210 output (average bytes/packet)
  0 collisions
  Flags:
    <UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST>
  Hardware features:
    <CSUM_IPv4,CSUM_TCPv4,CSUM_UDPv4,VLAN_MTU,VLAN_HWTAGGING,WOL>
  Supported media types on vr0:
    media none
    media 10baseT
    media 10baseT, mediaopt full-duplex
    media 100baseTX
    media 100baseTX, mediaopt full-duplex
    media autoselect
To force the interface to use a particular media type, 
nsh(interface-vr0)/media 10baseT

[no] mediaopt option

Set or remove media options such as full-duplex / half-duplex.

e.g to set vr0 interface to full-duplex mode:

nsh(interface-vr0)/mediaopt full-duplex

nsh(interface-vr0)/no mediaopt full-duplex

[no] auth proto pap | chap name name-text key key-text

Set or remove the PPP authentication parameters for the interface.

[no] peer proto pap | chap name name-text key key-text [flag callin | norechalange]

Set or remove configured peer PPP authentication parameters for the interface.

[no] tunnel source-ip destination-ip [ttl 0-255] [df] [ecn]

Set or remove tunnel assignments with this command. Note that tunnel assignments are only valid on gif and gre interfaces at this time. TODO

nsh(interface-gre0)/tunnel 12.3.3.3 12.6.6.6

[no] tunneldomain [rdomain-id]

Set or remove tunnel routing domain over which tunnel encapsulated packets are to be exchanged between tunnel ip endpoints.

[no] txprio [0-7 | packet | payload]

Set or remove configured transmit priority of the headers of a tunnel interface. Valid options are standard traffic priority values (0-7) or set the headers according to encapsulated packet or payload priority.

E.g. to set the priority of headers of the tunnel gre1 to match that of the payload.

nsh(interface-gre1)/txprio payload

[no] rxprio [0-7 | packet | payload]

Set or remove configured receive priority of the headers of a tunnel interfaces are standard traffic priority values (0-7) or set the headers according to encapsulated packet / payload priority).

E.g. to set the priority of headers of tunnel gre1 manually to 7 regardless of payload:

nsh(interface-gre1)/rxprio 7

[no] vnetid [0-16777215 | 1-4094]

Set or remove the 24 bit virtual network identifier tag. Virtual network identifier tags are typically used in large multi tenant VXLAN multiple routing domain environments. If vnetid invoked inside a vlan interface the acceptable range is the standard 12-bit vlan id 1-4094 of the IEEE 802.1Q VLAN tag.

E.g. set gre1 vnetid to 8192.

nsh(interface-gre1)/vnetid 8192

[no] vnetflowid

Allow or disallow the interface to use a portion of the virtual network identifier space as a flow identifier. This allowOBs loadbalancing of the encapsulated traffic over multiple links.

E.g. enable vnetflowid load balancing for gre1.

nsh(interface-gre1)/vnetflowid

[no] parent parent-interface

Set or remove the parent interface for a vlan interface

E.g. set the parent interface of vlan1024 to em0.

nsh(interface-vlan1024)/parent em0

[no] patch pair-interface-name

Set or remove patch (layer1+ connection) between current interface and another pair(4) interface. A patch is a CPU efficient way of forwarding packets between two pair(4) interfaces, the forwarding mechanisim is layer1 like a cable what is sent by one pair(4) interface is recived by the other pair(4) interface and vice versa. Patch can only connect two pair(4) interfaces, no other interface types are supported.

E.g. To connect pair1 and pair2 interfaces with a virtual patch cable.

nsh(p)/interface pair1

nsh(interface-pair1)/patch pair2

[no] keepalive [period count]

Enable or disable gre / gre based interfaces sending keepalive packets sent every period seconds. A second timer is run with a timeout of count * period. If no keepalive response is received during that time, the link is considered down. The minimal usable count is 2 since the round-trip time of keepalive packets
needs to be taken into account.

E.g. enable keepalives on interface gre1 at 1 second interval and down count of 3.

nsh(interface-gre1)/keepalive 1 3

[no] mplslabel [16-1024575]

Set or remove the local MPLS label to the specified mplslabel this label on the local system shall de-encapsulated for input. (MPLS labels 0-15 inclusive are reserved labels and cannot be used). MPLS labels are supported for mpe(4), mpip(4) and mpw(4) interfaces.

E.g. set the mpls label to 10240 on interface mpe1.

nsh(interface-mpe1)/mplslabel 10240

[no] pwe neighbor [neighbor-label neighbor-ip]

Set or remove the configuration of the PWE3 neighbor, configured with an MPLS neighbor label and a neighbor ip. neighbor-label can be any value 16-1024575. neighbour-ip should be set to the ip address of the PWE3 neighbor.

[no] pwe [cw]

Enable or disable the use of PWE3 Control Word. The control word is used to facilitate fragmentation across mpls packets. This option supported on the mpip(4) and mpw(4) interfaces.

E.g. enable control word on an mpls pseudo wire interface mpw1.

nsh(interface-mpw1)/pw cw

[no] pwe [fat]

Enables or disables the use of PWE flow-aware transport FAT flow label. This option supported on the mpip(4) and mpw(4) interfaces.

E.g. Enable flow-aware transport flow label on mpls ip interface mpip1

interface-mpip1)/pw fat

[no] syncdev syncdev-name

Configures or removes the data interface through which pfsync update messages are sent. Note that the pfsync protocol currently includes no authentication method. It is advisable to layer authentication, signing and (possibly encrypted tunnels for the underlay interfaces. For simplicity on co-located pfsynced firewalls a secure way to use pfsync, is through a a direct (layer1 (i.e. no switches)) cable connecting directly between two pfsync capable devices (i.e. a conenction made with an ethernet patch cable). This command is valid only for pfsync(4) interfaces.

E.g. Set the physical interface em1 as the pfsync0 syncdev

nsh(interface-pfsync0)/syncdev em1

[no] syncpeer [ipv4-peer-pfsync-address]

Set or remove a manually entered ip address of the pfsync interface of a peer pf sync firewall. By default, state change messages are sent out on the synchronisation interface using IP multicast packets to the 224.0.0.240 group address. When syncpeer ip address is set the sync messages are sent via unicast to the specified ipv4-peer-pfsync-address. This command is valid only for pfsync(4) interfaces.

E.g. set sync messages to use unicast peer ip address 192.0.0.10 which is reachable via syncdev interface.

nsh(interface-pfsync0)/syncpeer 192.0.0.10

[no] maxupd 0-255 [defer]

Configures or removes the maximum number of updates which are collapsible into one for a single state. The default value is 128. The transmission a pfsync update packet shall be delayed by a maximum of 1 second. The defer flag defers the first packet of each connection from being delivered until the state is active on pfsync peer. This command is valid only for pfsync(4) interfaces.

E.g. set the pfsync to aggregate the maximum number of state changes before sending a pfsync update message (reduce pfsync traffic updates)

nsh(interface-pfsync0)/maxupd 255

E.g. set pfsync to aggregate a max of 32 state changes in one packet and delay fowarding of new connection packets until peers pfstate is synchronised use:

nsh(interface-pfsync0)/maxupd 32 defer

[no] vhid [1-255]

Configure or remove the virtual host ID for the Common Address Redundancy CARP protocol. vhid is valid for carp(4) interfaces only.

E.g. set virtual router host id on carp0 interface to 12.

nsh(interface-carp0)/vhid 12

[no] advbase [0-254]

Configure or remove the advertisement interval in seconds for the master host to advertise itself. advbase is valid for carp(4) interfaces only.

E.g. set the advertisement interval to 10 seconds on carp0 interface.

nshpromot(interface-carp0)/advbase 10

[no] advskew skew

Configure or remove the carp advertisement skew on the active carp interface. The formula is advbase + (advskew / 255). If the master does not advertise within three times this interval, this host assumes master role and starts advertising as master. The device with the highest advskew value is least likely to become master, a device with a high advskew only becomes master if all other devices are offline. advskew is valid for carp(4) interfaces only.

E.g. set the advskew to 20 on carp0 interface.

nsh(interface-carp0)/advskew 20

[no] carppass passphrase

Configure or remove the CARP passphrase of the active interface. The passphrase can be up to 19 characters long and can contain special characters. There is no passphrase by default. carpass is valid for carp(4) interfaces only.

E.g. Set carp0 carp passphrase to 19CharPassphrase!!! including exclamation marks.

nsh(interface-carp0)/carppass 19CharPassphrase!!!

[no] carpdev [interface-name]

Set or remove the interface on which the selected carp interface's carp advertisements are sent and received. The carpdev is the "real interface" over which the carp virtual IP is accessible. carpdev is valid for carp(4) interfaces only.

E.g set carp0 to use vlan10 as its carpdev.

nsh(interface-carp0)/carpdev vlan10

[no] carpnode [vhid] [advskew] [state]

Set or remove carpnode parameter on a carp interface. carpnode facilitates loadbalancing across carp nodes. Each carpdevice that you wish to loadbalance should have a carpnode and advskew entry on each carp device. carpnode is valid for carp(4) interfaces only.

E.g. For a 3 node carp cluster, one can setup carpnode loadbalanced entries as follows.

on carp router 1

nsh(interface-carp0)/carpnode 1 10
on caro router 2 
nsh(interface-carp0)/carpnode 1 20
on carp router 3 
nsh(interface-carp0)/carpnode 1 30

[no] carppeer [peer-ip-address]

Set or remove the carppeer ip address of a carp peer on the active carp interface. carppeer is valid for carp(4) interfaces only.

E.g. set carppeer to 10.2.3.4 on carp0 interface.

nsh(interface-carp0)/carppeer 10.2.3.4

[no] balancing [none | ip | ip-stealth | ip-unicast]

Set or remove the balancing mode on the active carp interface. Valid balancing modes are as follows:

  • none no load-balancing.
  • ip IP load balancing on top of Layer 2 multicast MAC (requires multicast mac support on the network switch)
  • ip-stealth carp wont send packets with its own virtual MAC address as the source. Stealth mode prevents a switch from learning the virtual MAC address, therefore the switch would unicast flood traffic to all switch ports
    (unless there is some swithc acls to prevent flooding unnecessarily.
  • ip-unicast Used in conjunction with a HUB or a switch that can replicate packets (monitoring or mirror) or other non-standard switch forwarding mechanism.
Note: IP balancing is being used on a firewall, it is recommended to configure the carpnodes in a symmetrical manner. This is achieved by simply using the same carpnodes list on all sides of the firewall. This ensures that packets of one connection pass in and out on the same host and are not routed asymmetrically.

balancing is valid when used in carp(4) interfaces.

E.g. enable standard IP balancing over layer2 multicast mac on carp0 interface

nsh(interface-carp0)/balancing ip

[no] pflow [sender sender-ip receiver receiver-ip:port] [version 5 | 9 | 10]

Set or remove pflow export to a pflow interface. plfow without arguments displays command help. To set a up a pflow export the sender-ip and receiver-ip:port must be specified. The specified pflow sender-ip address must exist on an interface on the system already. The receiver-ip:port is the address of the flow collector in your network. version specifies the export flow prtocol i.e. netflow version (5 or 9) or the standardised IPFIX (10).

The pflow interface attempts aggregate multiple pflow records in one export UDP packet. The aggregation algoritim record for longer than 30 seconds. The packet size and thus the maximum number of flows is controlled by the mtu of the inteface the flows are exported via.

There is a one-to-one correspondence between packets seen by bpf(4) on the pflow interface and packets sent out to the flow receiver. I.e. if a packet with 30 flows on pflow, then the same 30 flows were sent out to the receiver.

pflow command is valid only on a pflow(4) interface.

E.g. to setup a pflow export from 10.1.1.1 to an IPFIX flow collector listening on another server on 10.1.1.2 port 4739.

nsh(p)/interface pflow0

nsh(interface-pflow0)/pflow sender 10.1.1.1 receiver 10.1.1.2:4379 version 10

[no] debug

Set or remove the driver-dependant debugging flag for an interface. Useful for troubleshooting.

E.g to set debugging on a carp0 interface.

nsh(interface-carp0)/debug

[no] dhclrelay [dhcp-server-ip]

Set or remove dhcp relay service on the selected interface. The dhcrelay service listens on the selected interface for broadcast dhcp requests and then wrap the recieved broadcast request in a unicast ip packet and send it to a DHCP server specified by dhcp-server-ip.

E.g. set up dhcprelay on em0 and send requests to DHCP server 10.1.1.2

nsh(interface-em0)/dhcrelay 10.1.1.2

[no] wol

Enable or disable WOL (wake on lan) functionality on the selected interface. The interface and device bios or firmware must support WOL functionality.

E.g. to enable wake on lan on interface em0.

nsh(p)/interface em0

nsh(interface-em0)/wol

[no] mpls

Set or remove the MPLS flag on the selected interface,if mpls is set on the interface, the interface can send and receive mpls traffic.

E.g enable mpls on em0

nsh(p)/interface em0

nsh(interface-em0)/mpls

[no] inet6

Enables or disables ipv6 (inet6) link local address on the selected interface.

E.g. to enable ipv6 link local address on em0

nsh(p)/interface em0

nsh(interface-em0)/rad

[no] autoconf6

Enable or disable IPv6 auto configuration of Ipv6 address on the inteface. If autoconf6 is used alone (without temporary or autoconfprivacy being set on the interface then the autoconfigured address assigned is repeatable based on the MAC address of the interface (EUI64).

E.g. enable ipv6 autoconf address on the interface em0.

nsh(p)/interface em0

nsh(interface-em0)/autoconf6

[no] temporary

Configure or remove temporary address extension for stateless ipv6 autoconfiguaration. Temporary address assignments prevents a repeatable IPv6 address being assigned to the device to reduce the possibility of longterm external tracking of device (users) activity.

E.g. enable ipv6 autoconf with a temporary address on the interface em0.

nsh(p)/interface em0

nsh(interface-em0)/autoconf6

nsh(interface-em0)/temporary

[no] autoconfprivacy

deprecated. alias for Cm temporary above. Randomised addresses used to be called autoconfprivacy extensions for IPv6. Temporary addressing is a better description as privacy is not necessarily guaranteed by random IP addressing of a device.

E.g. enable ipv6 autoconf with "privacy" random temp address on the interface em0.

nsh(p)/interface em0

nsh(interface-em0)/autoconf6

nsh(interface-em0)/autoconfprivacy

[no] monitor

Configure or remove the monitor flag on the selected interface. Prevents the packets being processed in the network stack. Useful for intrusion detection sniffing and other diagnostics.

E.g. to enable ipv6 autoconf with "privacy" random temp address on the interface em0

nsh(p)/interface em0

nsh(interface-em0)/monitor

[no] wgpeer [public-key] [endpoint endpoint-ip:port | aip allowed-ip/prefix | psk pre-shared-key | pka interval-sec]

Configure or remove a wireguard peer with the peers publickey. The public-key is 32 bytes and base64-encoded.

pka interval-sec The persistent keep alive (pka) option sets the interval of keepalive packets in seconds. By default pka is is disabled i.e. the interval is 0. pka can help maintain connectivity to a peer that would otherwise be denied unsolicited traffic by an intermediate firewall or NAT device. Empirically, an interval of 25 seconds should suffice for most firewall configurations.

psk pre-shared-key The psk and preshared-key is optional but recommended as it supplements the public key cryptography with symmetric key cryptography.

aip allowed-ip/prefix Set the peer's allowed IPv4 or IPv6 addresses or prefixes for tunnelled traffic. The option be repeated to set multiple allowed ip/ranges. No addresses are allowed by default.

  • E.g set the a peer with the following requirements:
    • public key EJqeFntM71Dfvn/LDu88gLOWw8aeOHoxrshOEHFd6lQ=
    • from an ip of 10.1.2.3/32
    • with a keep alive packet interval of 25 seconds
nsh(p)/interface wg0

nsh(interface-wg0)/wgpeer EJqeFntM71Dfvn/LDu88gLOWw8aeOHoxrshOEHFd6lQ=
aip 10.1.2.3/32 endpoint 10.1.2.3:5252
psk oJo0kNhoF3TElGUXDg4b0H6IJvOiVCAc/tuaJa1nmVU=
wgkey [privatekey] Set the private key of the current wireguard interface. When wgkey is run without an argument a new wireguard key is generated for the interface. The privatekey is 32 bytes and base64-encoded.

E.g. set the private key of wireguard interface wg0 to a specific key.

nsh(p)/interface wg0

nsh(interface-wg0)/wgkey QComa+ca+mWih+Vl/5G/p+UwhYy17hw5vdwysZpIAn0=

[no] wgport 0-65535

Set or remove the configuration for the local UDP port to be used by the current wireguard interface when exchanging traffic with its wireguard peers. The interface binds to INADDR_ANY and IN6ADDR_ANY_INIT. If wgport is entered without an argument wireguard selects its own port automatically.

E.g. set wireguard interface wg0 to listen on 18443 UDP.

nsh(p)/interface wg0

nsh(interface-wg0)/wgport 18443

[no] wgrtable [rtable-id]

Set or remove the configuration of which routing table the Exchange traffic with peers under. The routing table choice is made using rtable-id which would be a value between 0 and 255 on a default OpenBSD kernel. The routing domain of the rtable does not need be in the same routing domain to which the interface is attached. wgrtable configures which rdomain the interface's tunnelled traffic appears.

E.g. set wireguard interface wg0 routing table to routing domain 5.

nsh(p)/interface wg0

nsh(interface-wg0)/wgrtable 5

[no] shutdown

Administratively turn off or on the current interface.

Using this command to shutdown and then turn up an interface resets the interface.

nsh(interface-de0)/shutdown
nsh(interface-de0)/no shutdown

see the following man pages for information

!man bridge

!man ifconfig

see the following man pages for information

!man pfctl !man pf.conf

nsh

OpenBSD has facilities for a user to be able to login directly to nsh without having access to a typical bourne or C shell.

Configure the user so they can run /bin/nsh from sudo. You must do this in /etc/sudoers, like this:

nshuser		ALL=NOPASSWD:/bin/nsh
(replace 'nshuser' with the actual user name)

Another way to configure sudoers is to allow all users that are members of a certain group to run NSH through sudo, like this:

%nshgroup	ALL=NOPASSWD:/bin/nsh
(replace 'nshgroup' with the actual group name)

Compile nwrapper (in the nsh distribution):

cc -static -o nwrapper nwrapper.c
Move nwrapper to a permanent location: 
mv nwrapper /bin/nwrapper
Change the user's shell to nwrapper: 
usermod -s /bin/nwrapper nshuser
(replace 'nshuser' with the actual user name)

Do NOT add nwrapper (or nsh) to /etc/shells. They should not be entered here.

Packet Filter Logging: This interface is used to pass traffic logged by the firewall to software which can record it. These interface names start with 'pflog'.

IPsec Loopback: This interface is used internally in the system to pass decapsulated IPsec traffic. All traffic from this interface has already been authenticated and unencrypted from the IPsec subsystem. This is useful when writing firewall rules. These interface names start with 'enc'.

Generic Tunnel: This interface is used to configure a network tunnel to another host or router. It follows the RFC1933 tunnelling standard. These interface names start with 'gif'.

Ethernet Bridge: This interface is used to configure layer 2 bridging between physical and virtual network ports on a system. These interface names start with 'bridge'.

Ethernet: This is a physical Ethernet interface, running at 10, 100, or 1000 megabits per second. These interface names are based on the name of the driver, and vary with different Ethernet chip types.

IEEE 802.1Q Virtual: This is a virtual Ethernet, Token Ring, or FDDI interface. It uses the IEEE 802.1Q protocol to segment real Ethernet interfaces into multiple layer 2 networks. These interface names start with 'vlan'.

Virtual: This is a virtual interface of any type. Often several different interfaces use this type. Several versions of OpenBSD use this type to denote virtual IEEE 802.1Q interfaces, described above.

PPP: This interface implements the Point to Point Protocol (PPP). PPP, described in RFC 1661, creates a network over serial communication lines. It is used over modem connections, direct serial links, leased lines, and over virtual IP based connections such as in SSH sessions. These interface names start with 'ppp' when referring to a version which supports serial and modem connections. Other interface types may also implement the Point to Point Protocol.

IEEE 802.11 Wireless: This interface implements the IEEE 802.11 wireless LAN protocol. Many implementations of this network have little or no security unless used with proper encryption such as IPsec. These interface names are based on the name of the driver, and vary with different wireless chip types.

TODO

There are several special interfaces.

The gre interface allows for tunnel construction using the Cisco GRE encapsulation protocol.
You can use the tunnel command under interface mode to create a tunnel.

nsh(interface-gre0)/tunnel 1.2.3.4 5.5.5.5
enc (IPsec Loopback)

enc (specifically, enc0) is the encapsulating interface. It is a software loopback mechanism used to control non-encapsulated IPsec traffic using the pf firewall ruleset. It allows an administrator to see outgoing packets before they have been processed by IPsec, or incoming packets after they have been processed.

All traffic out of enc0 is already decrypted and authenticated via IPsec. Thus, it is helpful when writing firewall rulesets.

The serial line Point-to-Point protocol uses this interface.

The Serial Line Internet Protocol uses this interface.

tun (Tunnel Interface)

This is another software loopback mechanism. It allows user processes to create their own virtual network interfaces. It is used by the PPPoE implementation.

This interface is used for RFC 1933 IPv[46] to IPv[46] tunnels.

nsh(interface-gif0)/tunnel 1.2.3.4 5.5.5.5
tunnels can be used between rdomains. 
nsh(interface-gif0)/tunnel 1.2.3.4 5.5.5.5 rdomain 5

Packets logged from the packet filter are visible on this interface

This interface type allows virtual LANs to be setup over an Ethernet port using the 802.1Q protocol. E.g. setup a virtual interface with the 192.168.44.1 IP address, with 802.1Q trunking on the fxp3 physical interface, and a vlan ID of 4.

nsh(interface-vlan0)/vnetid 4

nsh(interface-vlan0)/parent fxp3

nsh(interface-vlan0)/ip 192.168.44.1/24

This interface type allows virtual LANs to be setup over an Ethernet port using 802.1AD provider bridge.

This product includes software developed by the University of California, Berkeley and its contributors.

This product includes software developed by Jason L. Wright

This product includes software developed by the NetBSD Foundation Incorporated and its contributors.

EDITOR was used to specify the name of an (old-style) line editor, such as ed(1), and VISUAL was used to specify a (new-style) screen editor, such as vi(1). Hence if VISUAL is set, it overrides EDITOR. TODO

/etc/nshrc
global configuration file
~/.profile
user's login profile
/etc/shells
shell database
/etc/suid_profile
privileged shell profile

ed(1), mg(1), stty(1), vi(1), bgpd.conf(5), dhcpd.conf(5), ospf6d.conf(5), ospfd.conf(5), pf.conf(5), relayd.conf(5), shells(5), environ(7), script(7), pf(4), resolv.conf(5), bgpd(8), dhcpd(8), dvmrpd(8), eigrpd(8), ftpd(8), ftp-proxy(8), ifstated(8), iked(8), inetd(8), ipsecctl(8), ldapd(8) ldpd(8), npppd(8), ntpd(8), ospf6d(8), ospfd(8), pfctl(8), relayd(8), ripd(8), rad(8), sasyncd(8), smtpd(8), snmpd(8), sshd(8), tftp-proxy(8), tftpd(8),

Chris Cappuccio, http://www.nmedia.net/nsh/, 2014.

Chris Cappuccio, https://github.com/yellowman/nsh, 2022.

Stephen G. Kochan and Patrick H. Wood, UNIX Shell Programming, 3rd Edition, Sams, 2003, ISBN 0672324903.

This shell was originally designed and written by Chris Cappuccio <chris@nmedia.net>, and is now co-maintained by Tom Smyth <tom.smyth@wirelessconnect.eu>.

May 5, 2022 OpenBSD 7.3