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.
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.
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.
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
.
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
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.
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
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:
Configure updates (Business versions only)
See more practical examples, such as setting up the RESTCONF API
Configure IPsec tunnels
Configure time synchronization