NSH // Network Shell Manual // Chris Cappuccio <chris@nmedia.net>

Copyright (c) 2003-2023 Chris Cappuccio

NOTICE: this page is now deprecated and is provided for historic information on 
the NSH project

The most authoritive source of information on nsh is currently in the manual nsh.8, which is installed with nsh on any OpenBSD system that had nsh installed since late 2022.

To view the manual, simply type on (your shell via terminal or console  or ssh ) 

man nsh 

or from within nsh type 

!man nsh

these commands should display the nsh manual as relates to version of nsh installed on your system.

[The nsh manual can be viewed here](https://github.com/yellowman/nsh/wiki/NSH-Manual-page)


Contents
--------

1. Overview

2. Installation

3. Main mode commands

4. Interface mode commands

5. Bridge mode commands

6. PF mode commands

7. Adding system users to nsh

Appendices

A. Explanation of interface types

B. Interface flags

C. Configuration examples

D. ALTQ notes

E. Interface-specific notes

Section 1 > Overview
--------------------

Network Shell is a command line interface designed to facilitate network
configuration on the OpenBSD operating system. The command line notation
is simple and terse. The command line interface is loosely modeled around
the concepts used in Cisco's popular interface. Typically, only values
changed from default get saved in the configuration, giving system/network
administrators a quick view of the unique configuration on the given,
local system.

NSH is a shell to the OpenBSD kernel's networking functions.  The kernel
handles routing of packets, firewalling, network address translation,
rate limiting, bandwidth queueing, LAN bridging, IP tunneling, and
encryption (IP security).  NSH provides simple wrappers around these
functions to aid you in setting up a network.  The goal of this software
is to make the command syntax uniform, and bring all configuration together
with a single configuration file.

Some programs, such as ipsecctl, pfctl (and anything else handled from
ctl.c) simply have their native configuration files encapsulated within
the NSH configuration framework. No effort is made by NSH to obfuscate
their configuration in any way, the default configuration syntax
provided by these programs is already preferrable. NSH simply gives the
administrator a way to keep all configuration in one place.

Section 2 > Installation
------------------------

If you are using flashrd, please follow the NSH installation directions in the
flashrd FAQ for additional details.

NSH replaces /etc/netstart on a standard OpenBSD system.  To implement NSH on
such a system, you first need to convert your standard configuration into one
which is compatible with NSH's syntax.  You need to compile NSH in order
to use it.  NSH currently requires OpenBSD 5.1 or a later version. It may be
partially or fully compatible with Bitrig, but is currently untested there.
To compile NSH:

$ tar xvzf nsh.tar.gz
...
$ cd nsh
$ make
...

When this is done, you will have a binary in the nsh directory named 'nsh'.
Copy this to /bin/nsh or /usr/local/bin/nsh.  

# cp nsh /bin/nsh

The next step is to copy over the appropriate script which will save the
permanent configuration. 

If /etc is read-only and /var/run is read-write, you need to use the
save-ro.sh script:

# cp save-ro.sh /usr/local/bin/save.sh

Make sure that save-ro.sh actually takes the appropriate actions to make
/etc a read-write partition.  (Or, modify it to move nshrc to a different
location that can be written to.  Of course, the nsh startup command must
reflect this location as well.)

If /etc and /var/run are read-write, you need to use the save-rw.sh script:

# cp save-rw.sh /usr/local/bin/save.sh

To create nsh's initial configuration, run nsh on your router/firewall
which is already configured, and save the running configuration to disk,
as detailed below.  Nsh will merge your PF/NAT/ALTQ rules into /etc/nshrc.
When you use the 'write-config' command, NSH will learn your configurations
from the running kernel.  It will enter everything that is currently configured
into the nsh startup file.

# cp /etc/pf.conf /var/run/pf.conf.0
# cp /etc/dhcpd.conf /var/run/dhcpd.conf.0
# cp /etc/ssh/sshd_config /var/run/sshd.conf.0
# mv /etc/resolv.conf /var/run/resolv.conf.0
# ln -s /var/run/resolv.conf.symlink /etc/resolv.conf
# mv /etc/motd /var/run/motd.0
# ln -s /var/run/motd.0 /etc/motd
# nsh
% NSH v1.0
nsh/enable
nsh(p)/pf enable
nsh(p)/dhcp enable
nsh(p)/sshd enable
nsh(p)/dns local-control
nsh/write
% Configuration saved
nsh/quit

At this point, you should inspect and edit /etc/nshrc by hand to ensure that
it does exactly what you want.  Since it reads the entire configuration out of
the kernel, you may find things that you did not intend to save permanently.

You may wish to use nsh to control sshd, pf, inetd, and other daemons that
OpenBSD normally executes out of /etc/rc and /etc/netstart. To disable the
automatic start of these daemons and services, tell OpenBSD not to load
them.

rcctl disable sshd pf ntpd resolvd

Remove any networking config from /etc/ that conflicts with nsh, such
as /etc/hostname.*, /etc/mygate, and daemons from /etc/rc.conf.local that
you wish to control via NSH. (If you start network daemons from
/etc/rc.conf.local, rather than using NSH, you will not be able to control
their configuration file through NSH.)

Add nsh's start command to the top of /etc/rc.local:

/usr/local/bin/nsh -i /etc/nshrc | tee /var/run/nsh.out

You may even want verbose output to see how nsh parses its' rc file:

/usr/local/bin/nsh -vi /etc/nshrc | tee /var/run/nsh.out

In case you miss it during boot, system console output is also logged in the
kernel message buffer and can be seen with "dmesg -s".

You are done.  When NSH starts from /etc/rc.local, it will automatically load up
the network configuration into the kernel.  At this point, you are free to
view and manipulate the configuration from nsh.


Section 3 > Main mode commands
------------------------------

All nsh modes give you basic command line editing features.  You can
use the up arrow on most keyboards to go through the last commands
you entered and repeate them.  Any command that takes action in the
system can be reversed by prefixing it with 'no '.

Any command can be abbreviated.  For example, 'show interface' can
be written as 'show int'.  A command like 'show i' is too much of an
abbreviation, since it matches 'show interface', 'show ipstats', 'show
icmpstats', and so on.  If you enter an ambiguous command, nsh will
tell you so.

nsh/show i
% Ambiguous argument i

help
----

When you enter NSH, you will see the prompt.  It starts with your
machine name and a forward slash.  For simplicity, our example machine
name here is 'nsh'.  At the prompt, you can enter commands detailed in this
document.  The first command is simply 'help' or '?', which brings up
the main menu of commands.

nsh/?
% Commands may be abbreviated.
% Commands are:

  rtable       Routing table switch
  show         Show system information
  enable       Enable privileged mode
  ping         Send IPv4 ICMP echo request
  ping6        Send IPv6 ICMP echo request
  traceroute   Print the route to IPv4 host
  traceroute6  Print the route to IPv6 host
  ssh          SSH connection to remote host
  telnet       Telnet connection to remote host
  verbose      Set verbose diagnostics
  editing      Set command line editing
  who          Display system users
  ?            Print help information
  quit         Close current connection


enable
------

Many commands require privileged access to execute.  If you know the
correct password, you can obtain privileged access.  The menu of commands
increases when you enter privileged mode.

nsh/enable
Password:
nsh(p)/?
% Commands may be abbreviated.
% Commands are:

  hostname      Set system hostname
  interface     Modify interface parameters
  rtable        Routing table switch
  group         Modify group attributes
  arp           Static ARP set
  bridge        Modify bridge parameters
  show          Show system information
  ip            Set IP networking parameters
  flush         Flush system tables
  enable        Enable privileged mode
  disable       Disable privileged mode
  route         Add a host or network route
  pf            Packet filter control
  ospf          OSPF control
  ospf6         OSPF6 control
  bgp           BGP control
  rip           RIP control
  ldp           LDP control
  relay         Relay control
  ipsec         IPsec IKEv1 control
  ike           IPsec IKEv2 control
  dvmrp         DVMRP control
  sasync        SA synchronization control
  dhcp          DHCP server control
  snmp          SNMP server control
  ldap          LDAP server control
  smtp          SMTP server control
  sshd          SSH server control
  ntp           NTP synchronization control
  nppp          PPP server control
  ifstate       ifstate server control
  ftp-proxy     ftp-proxy server control
  tftp-proxy    tftp-proxy server control
  tftp          TFTP server control
  dns           DNS rule control
  inet          Inet super-server control
  ping          Send IPv4 ICMP echo request
  ping6         Send IPv6 ICMP echo request
  traceroute    Print the route to IPv4 host
  traceroute6   Print the route to IPv6 host
  ssh           SSH connection to remote host
  telnet        Telnet connection to remote host
  reboot        Reboot the system
  halt          Halt the system
  write-config  Save the current configuration
  verbose       Set verbose diagnostics
  editing       Set command line editing
  who           Display system users
  !             Invoke a subshell
  ?             Print help information
  quit          Close current connection


enable secret
-------------

To set the password you must be in privileged mode. Set it either with
"enable secret <yourpassword>" or 
"enable secret <cipher> <crypted password>".
NSH only supports blowfish as cipher.

Examples:

nsh(p)/enable secret foo

or with an already crypted password:

nsh(p)/enable secret blowfish $2a$06$eQYswZjAHop5UFC8yle85uEqi/MCBhnWBi8IRU60LmkVvgZmtBiOm

You can generate a blowfish-crypted password using encrypt -b6.

rtable
------

The rtable command allows you to execute services, diagnostic commands 
(ping, traceroute) and set routes under alternate routing tables. Routing
tables in OpenBSD number from 0 to 255. 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 will be inititalized with a routing domain of 0.

An uninitialized routing table cannot be used to execute any services
or diagnostic commands.

To add a routing table for unique use in its own routing domain, the most
common use, add a routing domain through the interface configuration first.

nsh(p)/interface fxp0
nsh(interface-fxp0)/rdomain 2
nsh(interface-fxp0)/ip 100.64.0.2/30

Now you may add routes to rtable 2 and have them tied to the fxp0
interface.

nsh(p)/rtable 2 Production network
nsh(p-rtable 2)/route 0.0.0.0/0 100.64.0.1

If you wish to add a routing table to rdomain 0, you must initialize it
without a corresponding rdomain being created. Do not set the rdomain in
any interface, and instead simply create a static route.

nsh(p)/rtable 1 Management network
nsh(p-rtable 1)/route 0.0.0.0/0 127.0.0.1
nsh(p-rtable 1)/sshd edit
nsh(p-rtable 1)/sshd enable

If you initialize a routing table in this manner, you will later be unable
to joint it to a new rdomain.

The rtable command also supports unprivileged mode usage to execute
diagnostic commands.

nsh/rtable 1
nsh(rtable 1)/ping 100.64.0.1


hostname <hostname>
-------------------

Set system hostname.  Requires privileged mode.

nsh(p)/hostname firewall.xyz.com
firewall.xyz.com(p)/

verbose
-------

Verbose mode causes many nsh commands to display extra information.  It is
very useful in diagnostic and troubleshooting sessions to enable this
mode.

nsh/verbose
% Diagnostic mode enabled

If you do not wish to have the extra information displayed, you may
disable verbose mode.

nsh/no verbose
% Diagnostic mode disabled

ftp-proxy
---------

This activates the ftp proxy. NSH starts ftp-proxy on 127.0.0.1 by default.
Redirect rules in pf must be used to direct outside traffic from any
rdomain to the local tftp daemon.

tftp-proxy
----------

This activates the tftp proxy. NSH starts tftp-proxy on 127.0.0.1, port 6969
by default. Redirect rules in pf must be used to direct outside traffic from
any rdomain to the local tftp proxy.

pass in quick on $int_if inet proto udp from $lan to port tftp \
    divert-to 127.0.0.1 port 6969
pass out quick on $ext_if inet proto udp from $lan to port tftp \
    group proxy divert-reply

tftpd
-----

This activates the tftp daemon. NSH starts tftpd on 127.0.0.1, port 69
by default. Redirect rules in pf must be used to direct outside traffic from
any rdomain to the local tftp daemon.

write-config
------------

This will save the running configuration to the permanent configuration
space.  Upon the next startup of the system, the saved configuration will
be used.

nsh(p)/write-config
% Configuration saved
nsh(p)/

halt
----

This will shut down the system.  Requires privileged access.

nsh(p)/halt
% Shutdown initiated

reboot
------

This will reboot the system.  Requires privileged access.

nsh(p)/reboot
% Reboot initiated

show
----

The main diagnostic and informational command is 'show'.  

nsh/show ?
% Commands may be abbreviated.
% 'show' commands are:

  hostname        Router hostname
  interface       Interface config
  route           IPv4 route table or route lookup
  route6          IPv6 route table or route lookup
  sadb            Security Association Database
  arp             ARP table
  kernel          Kernel statistics
  bgp             BGP information
  ospf            OSPF information
  ospf6           OSPF6 information
  rip             RIP information
  ldp             LDP information
  ike             IKE information
  dvmrp           DVMRP information
  relay           Relay server
  dhcp            DHCP server
  smtp            SMTP server
  ldap            LDAP server
  monitor         Monitor routing/arp table changes
  version         Software information
  users           System users
  running-config  Operating configuration
  startup-config  Startup configuration
  ?               Options

show hostname
-------------

This will display the system's currently assigned hostname.

nsh/show hostname
% nsh

show interface
--------------

This command displays essential information about a system's network interfaces
and network bridges.  Using 'show interface' by itself will show information
about all interfaces and bridges available on a system.  Using 
'show interface <ifname>' will show information about a specific interface.

nsh/show interface lo0
% lo0
  Interface is up (last change 37d 11:02:55), protocol is up
  Interface type Loopback
  Internet address ::1/128, fe80::1%lo0/64, 127.0.0.1/8
  Routing Domain 0, MTU 33196 bytes
  3182 packets input, 1486429 bytes, 0 errors, 0 drops
  3182 packets output, 1486429 bytes, 0 errors, 0 unsupported
  467 input, 467 output (average bytes/packet)

"Interface is up" means that the interface is turned on in software. 
"Protocol is up" means that the interface is configured and ready to run.
The "Interface type" explains what the interface is used for on
the system.  Some interfaces are not intended to pass traffic for network
users, and instead handle internal functions on the system.  See
Appendix A for more information on common interface types.

"Internet address" shows the IPv4 and IPv6 addresses configured for the
interface, if any. IPv6 addresses with a % sign are "link-local" and
not valid outside of the context of the interface name specified.
MTU describes the Maximum Transmission Unit, the largest size of
a packet which the kernel will transmit on this interface.  

The statistics show the number of packets, bytes, errors, and dropped
packets in both incoming and outgoing directions.  The average input/output
sizes describes the median size of packets going in and out the interface.
Note that the total bytes in and/or out may not be accurate.  OpenBSD uses
an unsigned long type to hold the byte count.  When the byte count exceeds
the storage limit of an unsigned long (4,294,967,295 on a 32 bit architecture
or 18,446,744,073,709,551,615 on a 64-bit architecture), the counter will
overflow, causing it to roll over to 0.  The average packet size will be
inaccurate when the total byte count rolls over, because the total number of
packets will reflect bytes that are no longer counted.

With verbose mode enabled, 'show interface' will display the raw kernel
flags for an interface.  See Appendix B for an explanation of these flags.

nsh/show int lo0
% lo0
  Interface is up (last change 37d 11:04:41), protocol is up
  Interface type Loopback
  Internet address ::1/128, fe80::1%lo0/64, 127.0.0.1/8
  Routing Domain 0, MTU 33196 bytes
  3182 packets input, 1486429 bytes, 0 errors, 0 drops
  3182 packets output, 1486429 bytes, 0 errors, 0 unsupported
  467 input, 467 output (average bytes/packet)
  Flags:
    <UP,LOOPBACK,RUNNING,MULTICAST>

With a bridge, verbose mode will show spanning tree member states and
bridge members.

nsh/show int bridge0
% bridge0
  Bridge is up (last change 00:00:21), protocol is up
  Interface type Ethernet Bridge
  0 packets input, 0 bytes, 0 errors, 0 drops
  0 packets output, 0 bytes, 0 errors, 0 unsupported
  Flags:
    <UP,RUNNING>
  STP member state:
    sis0: listening

With an IEEE 802.11 wireless interface, verbose mode will show
the network ID, network key, and powersaving mode (if enabled).

nsh/show int athn0
% athn0
  BLah blah
  IEEE 802.11
    network id blah
    network key blah
    powersaving (111 ms)

With an interface that supports media commands, including Ethernet
and IEEE 802.11 wireless interfaces, verbose mode will show which
media types are available.

nsh/show int sis0
% sis0
...
  Supported media types:
    media none
    media 10baseT
    media 10baseT, mediaopt full-duplex
    media 100baseTX
    media 100baseTX, mediaopt full-duplex
    media autoselect

show route
----------

A dump of the routing table, including ARP entries.

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

The destination column is simply the destination network which the
route describes.  The gateway is the next hop for this route to pass through.
Gateways which are described as 'link#' are local area networks or members
of local area networks.

The flags are useful to determine if the kernel is using a particular
route or not.

U - up
  This route is active
G - gateway
  The destination of this route is behind a gateway (next hop).
H - host
  This route describes a host on the local network.
L - link layer
  The destination has been or needs to be discovered through a layer 2 protocol
R - reject
  This route is unreachable, and therefore marked unusable in the kernel
D - dynamic
  This is a dynamic route which has is managed through routing software on
  the local system (such as ripd, ospfd or bgpd)
S - static
  This is a static route set by a user

show ipstats
------------

This displays a variety of statistics related to Internet Protocol usage
related to both local machine and its gateway functions.

show ahstats
------------

This displays a variety of statistics related to Authentication Header
(IPsec) usage related to both the local machine and its gateway functions.

show espstats
-------------

This displays a variety of statistics related to Encapsulated Security Payload
(IPsec) usage related to both the local machine and its gateway functions.

show tcpstats
-------------

This displays a variety of statistics related to Transmission Control Protocol
usage on the local machine.

show udpstats
-------------

This displays a variety of statistics related to User Datagram Protocol usage
on the local machine.

show icmpstats
--------------

This displays a variety of statistics related to Internet Control Message
Protocol usage on the local machine.

show igmpstats
--------------

This displays a variety of statistics related to Internet Group Message
Protocol usage on the local machine.

show ipcomptats
---------------

This displays a variety of statistics related to IP Compression Protocol
(IPComp) usage related to both the local machine and its gateway functions.

show rtstats
------------

This displays a variety of statistics kept in the kernel's routing engine.

show mbufstats
--------------

The kernel has a private pool of memory buffers called 'mbufs'.  This
displays a variety of statistics kept in the kernel's memory management

show monitor
------------

This causes the user to enter monitor mode for the 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 will talk to
the kernel properly.

nsh/show version
% NSH v1.0
Compiled 03-Jan-13 22:08 by chris@nsh
uptime: 1 week, 1 day, 1 hour, 39 minutes
system: OpenBSD/i386 version 5.2
cpu: Geode(TM) Integrated Processor by AMD PCS ("AuthenticAMD" 586-class)
memory: 255MB
kernel: OpenBSD 5.2-current (FLASHRD) #8: Thu Jan  3 21:01:39 PST 2013
    root@mina.nmedia.net:/usr/src/sys/arch/i386/compile/FLASHRD
IFQ drops: ip 0 mpls 0

show running-config
-------------------

This shows the current running configuration on the system, including
interface and bridge configurations, routes, the system hostname, firewall
rules, and other information compiled by nsh.  See Appendix C for
example configuration files.

show startup-config
-------------------

This shows the startup configuration on the system, read from nshrc,
including interface and bridge configurations, routes, the system hostname,
firewall rules, and other information compiled by nsh.  See Appendix C for
example configuration files.

flush
-----

Flush will empty various system tables

flush routes
------------

This will empty the system routing table

flush arp
---------

This will empty the system arp cache and static arp table

flush bridge-dyn <bridge>
-------------------------

This will flush dynamically learned members from the named bridge

nsh/flush bridge-dyn bridge0

This would delete all dynamically learned members from bridge0.  Any
members set manually (static members) will not be removed.

flush bridge-all <bridge>
-------------------------

This will flush dynamically and statically learned members from the named bridge

nsh/flush bridge-all bridge0

flush bridge-rule <bridge> <interface>
--------------------------------------

This will flush all rules on the named bridge for a specifc interface.

nsh/flush bridge-all bridge0 sis0

flush history
-------------

This will clear the command history

disable
-------

Leave privileged mode, use this if you want to stay logged in but to not
trust your terminal area

route <destination>[/<prefixlen | netmask>] <gateway>
-----------------------------------------------------

You can add static routes with this command.  IPv4 addresses can be configured
with CIDR prefix length, or classic IP netmasks to describe routes.  The IPv6
address may only be configured with a prefix length. This command only runs
in privileged mode.

nsh(p)/route 192.168.0.0/16 1.2.3.4

is equivalent to:

nsh(p)/route 192.168.0.0/255.255.0.0 1.2.3.4

This command takes the 'no ' prefix to remove a route.  The gateway
is not necessary when using the 'no route' notation.

nsh(p)/no route 192.168.0.0/16

If you do not specify a mask, it will assume you are routing a host
address

nsh(p)/route 10.6.6.4 1.2.3.4

Routing flags may be defined after a route.

nsh(p)/route 127.0.0.0/8 127.0.0.1 reject

or

nsh(p)/route ::/96 ::1 reject

Flags:
------
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

Inits:
------
mtu <n>		RTV_MTU		Maximum transmission unit (MTU) size (this route only)
expire <n>	RTV_EXPIRE	Lifetime for a route (seconds)


quit
----

Leave NSH

verbose
-------

[no] verbose

Set verbose mode on.  (It defaults to off)

editing
-------

[no] editing

Set command line editing on.  (If defaults to on)

!
-

Invoke a shell command (requires privileged mode.)

Your system may have this feature disabled to enhance security.

nsh(p)/!ls
helloworld.c
nsh(p)/!
$ 

ip
--

Enable, allow, or set system 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:

  arpdown             Seconds before resending unanswered ARP requests
  arptimeout          Seconds for ARP entries to remain in cache
  forwarding          Enable IPv4 Forwarding
  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
  ah                  Allow Authentication Header
  sourceroute         Process Loose/Strict Source Route Options
  encdebug            Enable if_enc debugging
  send-redirects      Send ICMP redirects
  directed-broadcast  Allow directed broadcasts
  default-ttl         Set Default IP packet TTL
  ?                   Options

[no] interface <ifname>
-----------------------

nsh(p)/interface vlan0

If vlan0 does not exist, this will create the interface.  If it was possible
to create the interface, or if the named interface already exists, you
will noe be in the interface command mode, documented below in Section 4.

nsh(p)/no interface vlan0

Alternately, if vlan0 does exist, you can remove the interface with
the 'no interface' syntax.  This only works for interface types which
support creation and removal.

[no] ip arpdown <seconds>
--------------------------

nsh(p)/ip arpdown 20

Timeout (seconds) the system waits before resending an unanswered ARP request.

If the ARP system fails to resolve a MAC address, it will wait for this timer
before trying again. Lower settings will increase the broadcast traffic on the
underlying network while higher settings will increase the time it takes to
resolve a host on a lossy network.

[no] ip arptimeout <seconds>
-----------------------------

nsh(p)/ip arptimeout 300

Timeout (seconds) for ARP entries to remain in cache on this system.

When the system stops receiving ARP packets from the host, they will be removed
from the ARP cache, forcing broadcast and ARP resolution. Lower settings will
increase the broadcast traffic on the underlying network while higher settings
will 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.

[no] ip forwarding
------------------

nsh(p)/ip forwarding

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

[no] ip ipip
------------

nsh(p)/ip ipip

Allow IP-in-IP encapsulation.  

[no] ip gre
-----------

nsh(p)/ip gre

Allow Generic Route Encapsulation.  Must be used to enable gre interfaces.

[no] ip wccp
------------

nsh(p)/ip wccp

Allow GRE-based Web Cache Control Protocol packets to manage caching device.
Must be used to enable WCCP on gre interfaces.

[no] ip etherip
---------------

nsh(p)/ip etherip

Allow Ether-IP encapsulation

[no] ip ipcomp
--------------

nsh(p)/ip ipcomp

Allow IPComp compression to be used.

[no] ip esp
-----------

nsh(p)/ip esp

Allow IPsec Encapsulated Security Payload to be used.  Note this is a system
default.

[no] ip ah
----------

nsh(p)/ip ah

Allow IPsec Authentication Header to be used. Note this is a sysdem default.

[no] ip sourceroute
-------------------

nsh(p)/ip sourceroute

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

[no] ip encdebug
----------------

nsh(p)/ip encdebug

Print debugging messages for the if_enc interface to the kernel output.  
Requires a kernel compiled with option ENCDEBUG.

[no] ip send-redirects
----------------------

nsh(p)/ip send-redirects

Controls whether or not the system sends ICMP redirects to local hosts.  This
option is 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, it will
send an ICMP redirect to the originating host.  This redirect tells the host
the direct path on the network to send further packets.

[no] ip default-ttl <ttl>
-------------------------

nsh(p)/ip default-ttl 128

Sets the default ttl used on IP packets originating from this system.  

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 ?

Help menu


Section 4 > Interface mode commands
-----------------------------------

nsh(interface-vr0)/?
% Commands may be abbreviated.
% Type 'exit' 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
  mtu              Set Maximum Transmission Unit
  metric           Set routing metric
  link             Set link level options
  arp              Set Address Resolution Protocol
  label            Set MPLS Label
  lladdr           Set 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
  tunnel           Source/destination for GIF/GRE tunnel
  keepalive        GRE tunnel keepalive
  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
  vlan             802.1Q vlan tag and parent
  debug            Driver dependent debugging
  dhcrelay         DHCP Relay Agent
  shutdown         Shutdown interface
  wol              Wake On LAN
  mpls             MPLS
  inet6            IPv6
  autoconf6        IPv6 Autoconfigurable address
  autoconfprivacy  Privacy addresses for IPv6 autoconf
  trunkport        Add child interface(s) to trunk
  trunkproto       Define trunkproto
  ?                Options

[no] ip <address>/<prefixlen | netmask>
[no] ip dhcp
---------------------------------------

Set (or remove) the IPv4 or IPv6 address on an 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

or

nsh(interface-fxp0)/ip dhcp

DHCP client notes:

DHCP client mode will assume 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 will set the default gateway.  This behavior will be manually
configurable in a future release of NSH.

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) will trigger 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.

[no] alias <address>/<prefixlen | netmask>
------------------------------------------

This command is deprecated. Use the 'ip' command instead.

[no] mtu <value>
----------------

Set the interface Maximum Transmission Unit.  This is the maximum packet
size that the operating system will transmit.  Using 'no mtu' will set
the interface MTU back to the default value for that interface type.

nsh(interface-vr0)/mtu 1600

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 will fail if the specified mtu exceeds
the hardmtu value.

A larger MTU is particularly useful for features which stack tags,
such as PPPoE, MPLS tagging and QinQ (svlan) tagging.

[no] metric <value>
-------------------

Set routing metric for the interface.  Using 'no metric' will set 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 link XYZ' will remove
the specified link flags.  Using 'no link' will remove all link flags from
the interface.

nsh(interface-gre0)/no link 0

Each different interface type uses link flags for different purposes.  See
Appendix E for a detailed explanation of how to use link flags.

[no] arp
--------

Turn on or off the Address Resolution Protocol.  The default is on.

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

[no] nwid <id>
--------------

Set the network ID for an 802.11 capable interface.  Using 'no nwid'
will set it to the default value of a blank network ID.

[no] nwkey <key>
----------------

Set the WEP network key for an 802.11 capable interface.  Using 'no nwkey'
will turn off WEP.

[no] powersave [time]
-------------------

Set the 802.11 powersaving mode to X ms of time.  Using 'no powersave'
will set it to the default time.

[no] media <type> [instance]
----------------------------

Set the media type to X.  You can see the available media types on
an interface by setting verbose mode and looking at the interface.

nsh/v
% Diagnostic mode enabled
nsh/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>
----------------------

You can set or remove media options with this command.

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

[no] tunnel <src ip> <dest ip>
------------------------------

You can set or remove tunnel assignments with this command.  Note that
tunnel assignments are only valid on gif and gre interfaces at this time.
See Appendix E for more details.

nsh(interface-gre0)/tunnel 12.3.3.3 12.6.6.6

[no] syncdev <syncdev>
----------------------

This command is valid for pfsync interfaces only.  It configures the
data interface through which pfsync update messages are sent.  Note
that the pfsync protocol currently includes no authentication method.
Therefore, the only secure way to use it is through a network plug connecting
directly between two pfsync capable devices (such as a conenction made
with an ethernet crossover cable).

nsh(interface-pfsync0)/syncdev vr0

[no] maxupd <updates> [defer]
-----------------------------

This command is valid for pfsync interfaces only.  It configures the maximum
number of updates which are collapsable into one for a single state.  The
default value is 128. The defer flag defers the first packet of each connection
from being delivered until the state is active on pfsync peer.

nsh(interface-pfsync0)/maxupd 128 defer

[no] vhid <id>
--------------

This command is valid for carp interfaces only.  It configures the virtual
host ID for the Common Address Redundancy Protocol.  

nsh(interface-carp0)/vhid 1

[no] advbase <seconds>
----------------------

This command is valid for carp interfaces only.  If configures the
advertisement interval for the master host to advertise itself.  

nsh(interface-carp0)/advbase 64

[no] advskew <skew>
-------------------

This command is valid for carp interfaces only.  If configures the
advertisement skew.  The formula is advbase + (advskew / 255).  If the
master does not advertise within three times this interval, this host will
begin advertising as master.

nsh(interface-carp0)/advskew 20

[no] cpass <passphrase>
-----------------------

This command is valid for carp interfaces only.  It configures
the CARP passphrase.  There is no passphrase by default.

nsh(interface-carp0)/cpass mekmitasdigoat

[no] vlan <tag> parent <parent interface>
-----------------------------------------

You can set or remove vlan assignments with this command.  Note that vlan
assignments are only valid on the vlan inteface.  See Appendix E for more
details.

nsh(interface-vlan0)/vlan 4 parent fxp3

This would set vlan0 to use vlan ID 4 on parent (trunk) interface fxp3.

The parent interface must be a real, physical interface on the system.

[no] debug
----------

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

nsh(interface-xyz)/debug

[no] shutdown
-------------

Shut down or turn up an interface.

Using this command to shutdown and then turn up an interface will reset it.

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

?
-

This will display the command menu.

Section 5 > Bridge mode commands
--------------------------------

Section 6 > PF mode commands
----------------------------

Section 7 > Adding system users to 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.

1a. 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)

1b. 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)

2. Compile nwrapper (in the nsh distribution):

cc -static -o nwrapper nwrapper.c

3. Move nwrapper to a permanent location:

mv nwrapper /bin/nwrapper

4. 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.


Appendix A > Common interface types
-----------------------------------

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 tunneling 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 will all 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.


Appendix B > Interface flags
----------------------------

UP
  Interface is up
BROADCAST
  Broadcast address valid
DEBUG
  Turn on debugging (only some network drivers use this)
LOOPBACK
  Interface is a loopback network (internal to the machine) 
POINTOPOINT
  Interface is point-to-point link
NOARP
  Address Resolution Protocol is disabled on this interface
PROMISC
  Interface is in promiscuous mode, it will cause the system's software to
  receive all packets visible to the network card, even if they are not
  destined for this host
ALLMULTI
  This causes the interface to receive all multicast traffic, even for
  multicast networks that it was not signed up for
OACTIVE
  Transmission in progress
  An interface that displays this flag continuously may be stuck.  You
  may be able to reset an interface that is in this state by using and then
  reversing the 'shutdown' command from the interface menu.  For example,

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

SIMPLEX
  Can't hear own transmissions
LINK0
  This flag has different meanings with different interface types
LINK1
  This flag has different meanings with different interface types
LINK2
  This flag has different meanings with different interface types
MULTICAST
  This interface supports multicast


Appendix C > Configuration examples
-----------------------------------

See http://www.nmedia.net/nsh/

Appendix D > ALTQ notes
-----------------------

Appendix E > Interface-specific notes
-------------------------------------

There are several special interfaces.  

gre
---
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.

ppp (Point to Point Protocol)
---

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

sl (Serial Line Interface Protocol)
--

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.

gif
---

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

pflog
-----

Packets logged from the packet filter are visible on this interface

vlan
----

This interface type allows virtual LANs to be setup over an Ethernet
port using the 802.1Q protocol.  For instance, if you wanted to 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, you would do this:

nsh(interface-vlan0)/vlan 4 parent fxp3
nsh(interface-vlan0)/ip 192.168.44.1/24

svlan
-----

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, Inc. and   
its contributors.
