Tip

This is the documentation for the 23.11 version. Looking for the documentation of the latest version? Have a look here.

Zero-to-Ping: Getting Started

This document is a crash course in getting TNSR up and running quickly after installation. This document covers basic information on getting started with TNSR which guides the user starting from a default configuration until TNSR has upstream connectivity.

The topics included here are covered in more detail throughout the remainder of the documentation. Each section contains a list of additional related resources with more detail in a See Also box. Follow these links for more information on each topic.

First Login

When TNSR boots, it will present a login prompt on the console (video and serial). Login at this prompt using either the default tnsr account or an administrator account created during the installation process.

Note

For installations from ISO and for hardware shipped with TNSR preinstalled, the default password for the tnsr user is tnsr-default. For cloud-based installs such as AWS and Azure, by default the tnsr account can only login with key-based ssh authentication. See Default Accounts and Passwords for more information.

The tnsr user automatically enters the TNSR CLI when used to login interactively. Manually created administrative users do not have this behavior, and using them to login interactively will result in a login shell.

Alternately, if the host OS management interface was configured in the installer, login using an SSH client connecting to that interface.

See also

Changing the Password

The password for administrator accounts was set during the installation process, but the default tnsr account should have its password reset before making other changes.

Login to the tnsr account with the default tnsr-default password and change it using the host shell passwd command from the TNSR CLI:

tnsr# host shell passwd
Changing password for user tnsr.
Changing password for tnsr.
(current) UNIX password:
New password:
Retype new password:
passwd: all authentication tokens updated successfully.
tnsr#

Alternately, login in as an administrator and change the password for the default tnsr account using sudo:

tnsr# host shell sudo passwd tnsr
Changing password for user tnsr.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.
tnsr#

Note

These examples use the TNSR prompt and host shell command. The same commands may be used without the host shell prefix from a non-TNSR shell prompt.

Warning

Use a strong password for this account as it will be able to make changes to the TNSR configuration, unless restricted by a custom NACM configuration.

See also

Interface Configuration

There are two types of interfaces on a TNSR system: Host OS interfaces for managing the device and dataplane interfaces which are available for use by TNSR.

Host OS Management Interface

A host management interface may be configured manually in the installer or later in TNSR or in the operating system. See Installation for the full procedure to configure a host OS management interface during installation, and Host Interfaces for information on configuring host OS interfaces from within TNSR.

At a minimum, the host OS interface must have an IP address, subnet mask, and a default gateway configured. The default gateway is necessary so that the host OS may retrieve updates as that traffic does not flow through TNSR, but over the management interface. Additionally, other host traffic may flow through the management interface, such as the ping command from within the TNSR CLI.

If an interface was not configured for management in the installer, it will need to be manually changed back to host OS control and then configured for network access. See Remove TNSR NIC for Host Use for instructions on how to return an interface from TNSR back to host OS control so it can be used for management. This procedure will require rebooting the TNSR device.

Consult Ubuntu 22.04.2 documentation for the specifics of network configuration for other environments.

Warning

Once the Host OS is capable of reaching the Internet, check for updates (Updating TNSR) before proceeding. This ensures the security and integrity of the router before TNSR interfaces are exposed to the Internet.

See also

Dataplane Interfaces

Interfaces not configured for host OS management control in the installer will be setup in such a way that they are available for use by the dataplane and thus TNSR.

Note

The default behavior of the dataplane with no interfaces defined in the configuration is to attach to all interfaces not in use by the host OS. Manually defining at least one device causes the dataplane to only attach to interfaces listed in the configuration. Thus, the best practice is to always define every interface required for use in the dataplane, even if only changing their names.

To see a list of available interfaces, start the TNSR CLI (Entering the TNSR CLI) and enter dataplane dpdk dev ?:

tnsr# configure
tnsr(config)# dataplane dpdk dev ?
0000:00:14.0           Ethernet controller: Intel Corporation Ethernet
  Connection I354 (rev 03)
0000:00:14.1           Ethernet controller: Intel Corporation Ethernet
  Connection I354 (rev 03)
0000:00:14.2           Ethernet controller: Intel Corporation Ethernet
  Connection I354 (rev 03)
0000:00:14.3           Ethernet controller: Intel Corporation Ethernet
  Connection I354 (rev 03)
0000:03:00.0           Ethernet controller: Intel Corporation I211 Gigabit
  Network Connection (rev 03)
0000:04:00.0           Ethernet controller: Intel Corporation I211 Gigabit
  Network Connection (rev 03) ( Active Interface enp4s0 )

This is an ideal time to set optional custom interface names since they are difficult to change later:

tnsr(config)# dataplane dpdk dev 0000:00:14.1 network name WAN
tnsr(config)# dataplane dpdk dev 0000:00:14.2 network name LAN
tnsr(config)# service dataplane restart
tnsr(config)# exit

Warning

Customizing Interface Names contains important information about limitations on valid interface names. Invalid or conflicting names will be rejected by TNSR.

The custom names set in that example will be used in the remainder of this document.

Note

Without custom names, interfaces are named after the port speed and bus location, such as GigabitEthernet0/14/1.

See also

TNSR Interfaces

Next, the interfaces inside TNSR must be configured with addresses and routing.

Optional: Access Lists

The best security practice is to filter inbound traffic so that only required traffic is allowed to pass. This step is optional, but the best practice is to at least apply the basic ACLs shown in this section, and then read through Access Lists for additional details.

First, create an ACL to only allow DHCP client responses, ICMP inbound, and DNS server responses for the DNS resolver configuration later in this document:

tnsr# configure terminal
tnsr(config)# acl internet-in
tnsr(config-acl)# rule 10
tnsr(config-acl-rule)# description Allow DHCP responses
tnsr(config-acl-rule)# action permit
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# protocol udp
tnsr(config-acl-rule)# source port 67
tnsr(config-acl-rule)# destination port 68
tnsr(config-acl-rule)# exit
tnsr(config-acl)# rule 20
tnsr(config-acl-rule)# description Allow ICMP
tnsr(config-acl-rule)# action permit
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# protocol icmp
tnsr(config-acl-rule)# exit
tnsr(config-acl)# rule 30
tnsr(config-acl-rule)# description Allow DNS Responses
tnsr(config-acl-rule)# action permit
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# protocol udp
tnsr(config-acl-rule)# source address 8.8.8.8/32
tnsr(config-acl-rule)# source port 53
tnsr(config-acl-rule)# exit
tnsr(config-acl)# rule 31
tnsr(config-acl-rule)# description Allow DNS Responses
tnsr(config-acl-rule)# action permit
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# protocol tcp
tnsr(config-acl-rule)# source address 8.8.8.8/32
tnsr(config-acl-rule)# source port 53
tnsr(config-acl-rule)# exit
tnsr(config-acl)# rule 32
tnsr(config-acl-rule)# description Allow DNS Responses
tnsr(config-acl-rule)# action permit
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# protocol udp
tnsr(config-acl-rule)# source address 8.8.4.4/32
tnsr(config-acl-rule)# source port 53
tnsr(config-acl-rule)# exit
tnsr(config-acl)# rule 33
tnsr(config-acl-rule)# description Allow DNS Responses
tnsr(config-acl-rule)# action permit
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# protocol tcp
tnsr(config-acl-rule)# source address 8.8.4.4/32
tnsr(config-acl-rule)# source port 53
tnsr(config-acl-rule)# exit
tnsr(config-acl)# exit

Next, create an ACL to reflect all outbound connections so return traffic is automatically permitted inbound:

tnsr(config)# acl internet-out
tnsr(config-acl)# rule 10
tnsr(config-acl-rule)# description Reflect all Outbound
tnsr(config-acl-rule)# action reflect
tnsr(config-acl-rule)# ip-version ipv4
tnsr(config-acl-rule)# exit
tnsr(config-acl)# exit

Finally, configure these ACLs on the interface connected to the Internet:

tnsr(config)# int WAN
tnsr(config-interface)# access-list input acl internet-in sequence 10
tnsr(config-interface)# access-list output acl internet-out sequence 10
tnsr(config-interface)# exit
tnsr(config)# exit

See also

WAN DHCP Client

In this example, WAN will be set as a DHCP client:

tnsr# configure terminal
tnsr(config)# interface WAN
tnsr(config-interface)# description Internet
tnsr(config-interface)# dhcp client ipv4
tnsr(config-interface)# enable
tnsr(config-interface)# exit

See also

LAN Interface

Next, configure an address for the internal network:

tnsr(config)# interface LAN
tnsr(config-interface)# ip address 172.16.1.1/24
tnsr(config-interface)# description Local Network
tnsr(config-interface)# enable
tnsr(config-interface)# exit

See also

NAT

The global NAT options must be set first, and then NAT must be explicitly enabled. The configuration for NAT pools and interfaces can only be added once NAT is enabled.

The following commands configure TNSR to use NAT forwarding, endpoint-dependent mode NAT:

tnsr(config)# nat global-options nat44 forwarding true
tnsr(config)# nat global-options nat44 endpoint-dependent true

With the global options complete for this example, NAT must be enabled before the remaining options can be set:

tnsr(config)# nat global-options nat44 enabled true

Warning

To make changes to the global NAT options later, NAT must first be disabled, and then re-enabled after the changes are complete.

Now setup a NAT pool using the WAN interface address, and set the interfaces which will participate in NAT. In this example, the WAN interface is the outside NAT interface and the LAN interface is inside:

tnsr(config)# nat pool interface WAN
tnsr(config)# interface WAN
tnsr(config-interface)# ip nat outside
tnsr(config-interface)# exit
tnsr(config)# interface LAN
tnsr(config-interface)# ip nat inside
tnsr(config-interface)# exit

See also

DHCP Server

Setup a basic DHCP server on the LAN side to hand out addresses, also instruct clients to use TNSR as their gateway and DNS server.

tnsr(config)# dhcp4 server
tnsr(config-kea-dhcp4)# description LAN DHCP Server
tnsr(config-kea-dhcp4)# interface listen LAN
tnsr(config-kea-dhcp4)# lease lfc-interval 3600
tnsr(config-kea-dhcp4)# subnet 172.16.1.0/24
tnsr(config-kea-subnet4)# pool 172.16.1.100-172.16.1.245
tnsr(config-kea-subnet4-pool)# exit
tnsr(config-kea-subnet4)# interface LAN
tnsr(config-kea-subnet4)# option domain-name-servers
tnsr(config-kea-subnet4-opt)# data 172.16.1.1
tnsr(config-kea-subnet4-opt)# exit
tnsr(config-kea-subnet4)# option routers
tnsr(config-kea-subnet4-opt)# data 172.16.1.1
tnsr(config-kea-subnet4-opt)# exit
tnsr(config-kea-subnet4)# exit
tnsr(config-kea-dhcp4)# exit
tnsr(config)# dhcp4 enable

See also

DNS Server

Configure TNSR to act as a DNS server for local clients, using upstream forwarding DNS servers of 8.8.8.8 and 8.8.4.4:

tnsr# configure
tnsr(config)# unbound server
tnsr(config-unbound)# interface 127.0.0.1
tnsr(config-unbound)# interface 172.16.1.1
tnsr(config-unbound)# access-control 172.16.1.0/24 allow
tnsr(config-unbound)# forward-zone .
tnsr(config-unbound-fwd-zone)# nameserver address 8.8.8.8
tnsr(config-unbound-fwd-zone)# nameserver address 8.8.4.4
tnsr(config-unbound-fwd-zone)# exit
tnsr(config-unbound)# exit
tnsr(config)# unbound enable

Configure the DNS Resolver behavior of the TNSR dataplane network namespace to use unbound as its DNS server

tnsr(config)# system dns-resolver dataplane
tnsr(config-dns-resolver)# server localhost 127.0.0.1
tnsr(config-dns-resolver)# exit

Configure the DNS Resolver behavior of the host operating system to use the chosen upstream forwarding DNS servers directly, since the host namespace cannot access unbound running in the dataplane namespace:

tnsr(config)# system dns-resolver host
tnsr(config-dns-resolver)# server g1 8.8.8.8
tnsr(config-dns-resolver)# server g2 8.8.4.4
tnsr(config-dns-resolver)# exit

Note

The DNS resolution behavior of both namespaces may be left at the default values which will use the DNS servers provided by DHCP.

See also

Ping

From TNSR

The TNSR CLI includes a ping utility which will send an ICMP echo request to a target. This utility can operate in either the host or dataplane namespace (Networking Namespaces), and defaults to using the dataplane namespace.

tnsr# ping 203.0.113.1
PING 203.0.113.1 (203.0.113.1) 56(84) bytes of data.
64 bytes from 203.0.113.1: icmp_seq=1 ttl=64 time=0.700 ms
64 bytes from 203.0.113.1: icmp_seq=2 ttl=64 time=0.353 ms
64 bytes from 203.0.113.1: icmp_seq=3 ttl=64 time=0.590 ms
64 bytes from 203.0.113.1: icmp_seq=4 ttl=64 time=0.261 ms
64 bytes from 203.0.113.1: icmp_seq=5 ttl=64 time=0.395 ms
64 bytes from 203.0.113.1: icmp_seq=6 ttl=64 time=0.598 ms
64 bytes from 203.0.113.1: icmp_seq=7 ttl=64 time=0.490 ms
64 bytes from 203.0.113.1: icmp_seq=8 ttl=64 time=0.790 ms
64 bytes from 203.0.113.1: icmp_seq=9 ttl=64 time=0.155 ms
64 bytes from 203.0.113.1: icmp_seq=10 ttl=64 time=0.430 ms

--- 203.0.113.1 ping statistics ---
10 packets transmitted, 10 received, 0% packet loss, time 9001ms
rtt min/avg/max/mdev = 0.155/0.476/0.790/0.187 ms

Note

This is equivalent to dataplane ping 203.0.113.1 since the dataplane namespace is the default.

To ping from the host namespace, using the host OS environment and routing, specify the host namespace before the command:

tnsr# host ping 198.51.100.1
PING 198.51.100.1 (198.51.100.1) 56(84) bytes of data.
64 bytes from 198.51.100.1: icmp_seq=1 ttl=64 time=0.142 ms
64 bytes from 198.51.100.1: icmp_seq=2 ttl=64 time=0.109 ms
64 bytes from 198.51.100.1: icmp_seq=3 ttl=64 time=0.126 ms
64 bytes from 198.51.100.1: icmp_seq=4 ttl=64 time=0.110 ms
64 bytes from 198.51.100.1: icmp_seq=5 ttl=64 time=0.109 ms
64 bytes from 198.51.100.1: icmp_seq=6 ttl=64 time=0.120 ms
64 bytes from 198.51.100.1: icmp_seq=7 ttl=64 time=0.100 ms
64 bytes from 198.51.100.1: icmp_seq=8 ttl=64 time=0.086 ms
64 bytes from 198.51.100.1: icmp_seq=9 ttl=64 time=0.087 ms
64 bytes from 198.51.100.1: icmp_seq=10 ttl=64 time=0.088 ms

--- 198.51.100.1 ping statistics ---
10 packets transmitted, 10 received, 0% packet loss, time 8999ms
rtt min/avg/max/mdev = 0.086/0.107/0.142/0.021 ms

See also

From LAN Client

At this stage a LAN client will be able to connect to the network (port or switch) connected to the LAN interface. It can pull an IP address and other configuration via DHCP, resolve domain names via DNS, and reach hosts beyond TNSR using it as a gateway.

A ping executed on a client will flow through TNSR and replies will return.

Save the TNSR Configuration

TNSR maintains three separate configuration databases: startup, candidate, and running. The running copy is the active configuration. TNSR loads the startup copy at boot time.

To ensure the expected configuration is loaded when TNSR is rebooted, copy the running configuration to the startup configuration after making changes:

tnsr# configure
tnsr(config)# configuration copy running startup

Optionally, create a backup copy of the configuration which can be loaded later if necessary:

tnsr(config)# configuration save running backup.xml

See also

Next Steps

From here, click the Next button at the bottom of the page to continue on to the next section of the documentation, or choose a topic from the table of contents to the left.

Other suggested next steps include: