Ncsh in examples


Table of Contents

License
Ncsh in examples
Preface
Hello, world!
Interface setup
Wired interfaces
Bridges
VLAN
Ethernet protocol parameters: speed
PPTP tunnels
PPPoE connections
Traffic controls
SFQ queue
Shaping: TBF
Shaping: HTB
Packet filters
Creation and applying of packet filters
SNAT, DNAT and masquerading
Routing
Events
Netlink events
SNMP events

List of Examples

1. Basic interfaces setup
2. Static addresses on an ethernet device
3. Dynamic addresses on an ethernet device (dhcp)
4. Interface-to-MAC binding
5. Bridge setup
6. Bridge subinterfaces, binded to MAC addresses
7. VLAN setup
8. Another VLAN setup
9. Force ethernet speed
10. PPTP connection
11. PPTP connection
12. Queue definition inside an interface section
13. Define a queue as a function
14. SFQ queue
15. TBF queue, shape bandwith to 128Kbit
16. HTB queue: simple setup
17. HTB queue: class factory
18. HTB queue: l7-filter
19. Simple packet filter
20. SNAT setup
21. Masquerade setup
22. Static routes in the main routing table
23. Netlink events: interface recnfiguration
24. Netlink events: dynamic routing
25. SNMP events: catch linkUp from a device
26. SNMP events: restart a system service

License

Copyright (c) 2007 Connexion project, Peter V. Saveliev.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found on the GNU site[1].

Ncsh in examples

Preface

This document implies that you are familiar with IP networking basics. The document is a collection of sample configurations, not a reference guide. All available commands can be listed with autocompletion in the ncsh shell.

Hello, world!

Initially, ncsh is a network configuration tool, so, this “Hello, world!” will be from this area. One can try configuration either with editing /etc/connexion/config (and service restart) or via ncsh shell. Empty comments (!) are given for easy reading.

Example 1. Basic interfaces setup

!
configure network interfaces
	!
	! Loopback interface. It does not require
	! a special setup, so we just turn it up.
	! IP address 127.0.0.1/8 will be set up
	! by OS.
	!
	loopback
		enable
	!
	ethernet 0
		!
		! Address should be given in the form x.x.x.x/y,
		! where the mask is in the bit form. If omitted, it
		! defaults to /32.
		!
		address 10.0.0.1/24
			  

Interface setup

Wired interfaces

Wired interfaces can be configured with ethernet command. On a defined ethernet interface one can to set up addresses, L2 protocol speed (10, 100, 1000), ip access lists and traffic shaping.

Example 2. Static addresses on an ethernet device

!
configure network interfaces
	!
	ethernet 0
		!
		address 10.0.0.1/24
		address 10.0.0.2/24
		      

Example 3. Dynamic addresses on an ethernet device (dhcp)

!
configure network interfaces
	!
	ethernet 0
		!
		use dhcp
		      

ethernet command accepts as a parameter either interface number or it's name. In the first case, the number will be used to form name ethX, in the second — the name will be used as is.

The OS kernel names ethernet devices automatically, and it's choice not always the same as user's choice. Moreover, the interface numbers can chage from boot to boot. To solve this problem, ncsh uses interface-to-MAC binding (requires man:/ifrename(8) command). On can bind an interface to a MAC address with hwaddr command. The format of MAC address must be exactly the same as it shows ip link show command.

Example 4. Interface-to-MAC binding

!
configure network interfaces
	!
	! Example of interface rename
	! 
	ethernet uplink
		!
		hwaddr 52:54:00:12:34:58
		address 10.0.254.2/24
	!
	ethernet 0
		hwaddr 52:54:00:12:34:59
		address 192.168.0.1/24
		      

The configuration above assigns names uplink and eth0 to interfaces. Take notice that with normal boot process these interfaces would obtain names eth0 and eth1. Unlike some alternate network setup systems, ncsh permits to use ethX names for renaming. E.g., it can swap names eth0 and eth1 in the case when interfaces have got wrong names during system boot.

Warning

Interface-to-MAC binding requires to set an interface down before renaming. Considering that the renaming can affect several interfaces, one must be careful doing this operation.

There is an aggravating limitation in the interface renaming procedure in ncsh. Because the name-to-MAC binding is done with an interface node creation in the config tree, there is no way to change the binding without the node re-creation. One should use commands no ethernet 0 and commit to delete eth0 node and then create it again with ethernet 0. As an alternative, one can edit config and restart the system service with command service ncsh restart.

Bridges

Bridge interafce does a software layer 2 switching between several interfaces. To create such switch, one should use bridge command.

Example 5. Bridge setup

!
configure network interfaces
	!
	bridge 0
		!
		address 192.168.0.1/24
		!
		interface ethernet 0
		interface ethernet 1
		interface etehrnet 2
		      

One can specify hardware address for bridge subinterfaces. In this case, a subinterface will be added to the bridge by MAC, not by name, and probably will be renamed. Subinterface names can be either as it shown by ip link show command, or in the form ethernet X. The latter will be automatically resolved to ethX.

Example 6. Bridge subinterfaces, binded to MAC addresses

!
configure network interfaces
	!
	bridge 0
		!
		address 192.168.0.1/24
		!
		interface net1 hwaddr 52:54:00:12:34:58
		interface eth0 hwaddr 52:54:00:12:34:59
		interface ethernet 1 hwaddr 52:54:00:12:34:60
		
		      

VLAN

VLAN — Virtual LAN. It is a technology that permits to isolate IP traffic by creation of logical channels inside one physical channel. VLANs are wide supported by network equipment. To create a VLAN on ethernet or bridge interface, it is enough to add .X to the interface number, where X — VLAN number.

Example 7. VLAN setup

!
configure network interfaces
	!
	ethernet 0.511
		address 10.0.1.1/24
	!
	ethernet 0.512
		address 10.0.2.1/24
		      

Another type of VLAN configuration requires more characters to be typed, but maybe it looks more clearly. One can to create vlan secions under an interface section.

Example 8. Another VLAN setup

!
configure network interfaces
	!
	ethernet 0
		!
		vlan 511
			address 10.0.1.1/24
		!
		vlan 512
			address 10.0.2.1/24
		      

Ethernet protocol parameters: speed

The command speed must not be used to shape a traffic. The command is required only when one or both interfaces on the wire do not work on autonegotiated speed. This can be either when autonegotiation does nt work at all, when it works wrong or when either of interaces can not work on negotiated speed. Surely, this is a hardware bug in any case, but sometimes it happens. Then one may try force ethernet speed in a hope this will solve the problem.

Example 9. Force ethernet speed

!
configure network interfaces
	!
	ethernet 0
		!
		address 192.168.0.1/28
		!
		! Change protocol from FastEthernet (100Mbit, 802.3u)
		! to Ethernet (10Mbit, 802.3).
		!
		speed 10
		      

PPTP tunnels

Warning

PPP control modules are in the alpha development stage and not well tested. So, any feedback and wishes are welcome.

PPTP — point-to-point over tcp. It is a way to link together two hosts with a tunnel. PPTP is a well-known VPN solution and is widely supported by netowrk devices and operating systems.

PPTP connection requires an established route to VPN gateway. In other words, there should be at least one physical interface configured and VPN gateway should be reachable from the box.

Example 10. PPTP connection

!
configure network
	!
	interfaces
		!
		ethernet 0
			!
			! an external inerface
			!
			address 10.0.0.2/24
		!
		pptp office
			host vpn.somewhere.net
			user user.pptp
			option debug
			option maxfail 10
			optio nopersist
		      

For the moment, ncsh can not edit files /etc/ppp/pap|chap-secrets. So, user name and passwd should be added there before PPTP connection is set up. user command in the example just selects which credentials to use with this connection.

Commands option controls pppd parameters. PPTP and PPPoE modules have a default set of parameters which can be overrode by option commands, but one should know this default parameters:

lcp-echo-interval 60
ktune
connect /bin/true
persist
nodefaultroute
debug
maxfail 0
noauth
mtu 1280
		      

PPPoE connections

Warning

PPP control modules are in the alpha development stage and not well tested. So, any feedback and wishes are welcome.

For PPPoE connection one should specify at least user name and an interface to work on.

Example 11. PPTP connection

!
configure network
	!
	interfaces
		!
		pppoe internet
			interface ethernet 0
			acn provider
			user user.pppoe
		      

Traffic controls

For now, only outcoming traffic shaping is implemented in ncsh. It means that it is useful mainly on routers or servers, where outcoming traffic prevails.

Ingress policing support is in the todo. There is no imq support, and no such support is planned, because of imq was dropped due to unstable work.

Each traffic control queue requires an interface to operate on. Each interface can have only one root queue. In terms of ncsh it means that each interface section sould have at most one egress child. Beside of direct child definition, an egress can be applied with call. This way allows to define a queue and apply it to many interfaces.

Example 12. Queue definition inside an interface section

!
configure network interfaces
	!
	ethernet 0
		! ...
		egress sfq
			! ...
	!
	ethernet 1
		! ...
		egress htb
			! ...
		    

Example 13. Define a queue as a function

!
configure network
	!
	tc
		!
		egress htb
			! ...
			declare f1
		!
		egress sfq
			! ...
			declare f2
	!
	intrefaces
		!
		ethernet 0.511
			call f1
		!
		ethernet 0.512
			call f1
		!
		ethernet 1
			call f2
		    

SFQ queue

Most simple queue. SFQ stands for Stochastic Fairness Queueing. The goal of SFQ is to perform “fair” channel sharing between all connections. Most important SFQ parameters are perturb and limit. The former defines an interval (in seconds) of queue reconfiguration. The latter is a limit of packets that can be queued. Overlimit packets will be dropped.

Example 14. SFQ queue

!
! In examples we'll use both forms of queue
! definitions — direct and functions.
!
configure network interfaces
	!
	ethernet 0
		!
		! An IP address is here only for
		! plausibility
		!
		address 192.168.0.128/24
		!
		egress sfq
			!
			! reconfigure queue each 10 seconds
			!
			perturb 10
			!
			! queue not more than 512 packets
			!
			limit 512
		      

Shaping: TBF

Token Bucket Filter queue, actually, has nothing to do with filters in the mean of tc filter command. It is a simple classless queue that can control overall bandwith on an interface.

Example 15. TBF queue, shape bandwith to 128Kbit

!
configure network
	!
	interfaces
		!
		! Each VLAN will be shaped to 128Kbit,
		! ethernet — to 1Mbit
		!
		ethernet 0.510
			!
			address 10.0.0.1/24
			call shaper
		!
		ethernet 0.511
			!
			address 10.0.1.1/24
			call shaper
		!
		ethernet 1
			address 192.168.2.2/28
			call uplink
	!
	tc
		!
		egress tbf clients
			!
			! For a diversity, lets make a queue
			! with function. Seel call in
			! ethernet 0.X
			!
			declare shaper
			!
			burst 10240
			limit 10240
			rate 128Kbit
		!
		egress tbf uplink
			!
			declare uplink
			rate 1Mbit
	
		      

Shaping: HTB

But TBF does not fit when one must to shape traffic not on per-interface but on per-source basis and like that. In that case one should use Hierarchical Token Bucket.

Assume we have two interfaces, external ethernet 0 and internal ethernet 1. It is a router and we are to set up access to a resource with 10Mbit bandwith and to all other resources with 64Kbit. Lets the 10Mbit-favourite will be msn.com, 207.68.172.246. Clients are in two networks, 10.0.1.0/24 and 10.0.2.0/24. These network will have 64Kbit and 128Kbit access respectively.

Example 16. HTB queue: simple setup

!
confiure network
	!
	interfaces
		!
		! Internal interface
		!
		ethernet 0
			!
			address 10.0.1.1/24
			address 10.0.2.1/24
			!
			call shaper
		!
		! External interface to an interconnection
		! network, 192.168.0.0/28
		!
		ethernet 1
			!
			address 192.168.0.2/28
	!
	tc
		!
		egress htb
			!
			declare shaper
			!
			! One should define overall channel
			! bandwith for HTB to work correctly.
			!
			rate 100Mbit
			!
			! This command define a default call
			! for all unmatched traffic.
			!
			default 1
			!
			class 1
				!
				! Here all unmatched packets will go.
				!
				rate 9Kbit
			!
			class 2
				!
				! Share MSN on hig speed: we need to _talk_
				!
				match src 207.68.172.246
				!
				! The less priority number is, the earlier
				! it will work with packets. So, MSN
				! traffic will go in this callregardless
				! of dst ip.
				!
				priority 1
				!
				rate 10Mbit
			!
			class 3
				! Network 10.0.1.0/24, 64Kbit
				!
				match dst 10.0.1.0/24
				priotiry 2
				rate 64Kbit
			!
			class 4
				! Network 10.0.2.0/24, 128Kbit
				!
				match dst 10.0.2.0/24
				priority 2
				rate 128Kbit
		      

As it is clear, the example above shares bandwith of class over whole networks. It is not easy to setup 64Kbit for every host, because there should be a class for every host in the network. If you have no courage to define 252 classes for C network, you can use class-factory command.

Example 17. HTB queue: class factory

!
configure network interfaces
	!
	ethernet 0
		!
		address 10.0.1.1/24
		address 10.0.2.1/24
		!
		egress htb
			!
			rate 100Mbit
			!
			class-factory 10.0.1.0/24
				!
				! Each host of this network
				! will have 64Kbit
				!
				rate 64Kbit
			!
			class-factory 10.0.2.0/24
				!
				! And here —  128Kbit
				!
				rate 128Kbit
		      

There are cases, when one should shape connections that use non-standard or dynamic ports. Then one can use high-level packet analyser l7-filter. It should be noted that the result will be coorect not in 100%. Some protocols can be matched easier, some harder. Details are on the l7-filter project page: http://l7-filter.sourceforge.net/protocols

Example 18. HTB queue: l7-filter

!
configure network interfaces ethernet 0
	!
	address 10.0.0.1/24
	!  
	egress htb
		!  
		class 1
			rate 100Mbit
		!  
		class 2
			match l7 edonkey
			match l7 ftp
			match l7 socks
			rate 16Kbit
		!
		default 1
		rate 100Mbit
		      

Packet filters

Note

Packet filtering controls are implemented only in rudimentary mode. Only basic capabilities are supported, and only with binding to an interface.

Creation and applying of packet filters

For this moment, one can create packet filters only in configure network tc branch. Each filter should be defined as a function with declare command and applied with call command. The first parameter to the call command should be filter name, the second — filtering direction. There are three directions: in, out and forward; for packet that go to this box, out of this box and through it, respectively.

Example 19. Simple packet filter

!
configure network
	!
	interfaces
		!
		ethernet 0
			!
			address 10.0.0.1/24
			!
			! Call one packet filter for incoming
			! packets.
			!
			call bala in
	!
	tc
		!
		simple-acl any_name
			!
			! Declare this ACL as function bala
			!
			declare bala
			!
			! Rules itself. A rule contains:
			! * a priority
			! * packet action
			! * packet match pattern
			!
			rule 10 reject dport 22
			rule 20 reject dport 23
		      

SNAT, DNAT and masquerading

One of the frequent tasks of an office gateway is to provide Internet connection to workstations. IPv4 architecure forces us to use private addresses in such networks, and setup NAT (Network Address Translation) to communicate with Internet resources.

Example 20. SNAT setup

!
configure network
	!
	interfaces
		!
		! Internal (downlink)
		!
		ethernet 0
			!
			address 10.0.0.1/24
		!
		! Extenral (uplink)
		!
		ethernet 1
			!
			address 1.2.3.4/28
			!
			! SNAT rules will be created
			! in the same iptables table regardless
			! the direction.
			!
			call snat out
	!
	tc
		!
		simple-acl bala
			!
			declare snat
			!
			rule 10 snat tosrc 1.2.3.4
		      

DNAT can be set up likewise, except there should be todst command instead of tosrc.

In the case of dynamic extenral address, SNAT will not work. Then one should use masquerade command.

Example 21. Masquerade setup

!
configure network
	!
	interfaces
		!
		! Internal (downlink)
		!
		ethernet 0
			!
			address 10.0.0.1/24
		!
		! External (uplink)
		!
		ethernet 1
			!
			use dhcp
			!
			call masq out
	!
	tc
		!
		simple-acl bala
			!
			declare masq
			!
			rule 10 masquerade
		      

Routing

In general, routing is a set of rules that OS uses to define an output interface for a packet. GNU/Linux system allows more intelligent routing control. There are 255 routing tables, there is RPDB (Routing Policy Database) — rules to choose a routing table for a packet (in the simplest case).

By default, GNU/Linux uses three routing tables, main, local and default. Table main is the one, with wich all work via route and netstat -r commands. Table local contains rules that are created by OS kernel, and one should not edit it manually. Table default is empty and is the last in RPDB rules.

Beside of these there are 252 unused tables. For the moment, ncsh provides only low-level interface to the GNU/Linux routing engine, so some of it's capabilities can be not so plain for beginners. The interface will be improved in future releases.

Example 22. Static routes in the main routing table

!
configure network
	!
	interfaces ethernet 0
		address 10.0.0.2/24
	!
	! If no table name specified, ncsh assumes that
	! it is table main.
	!
	routing table
		route default via 10.0.0.1

		    

Events

One of the important ncsh capabilities is event handling. Now there are two event providers.

Netlink events

There are two types of netlink events implemented yet, “netlink.address” and “netlink.link”.

Some modules are already capable to handle netlink events, if they are provided. E.g. any interface section will do interface reconfiguration by netlink.link.add event. Bridge sections react not only to their own interface events, but to subinterfaces too: if there is no subinterface at the startup time, it will be added to a bridge in runtime, as soon as it will be created.

Example 23. Netlink events: interface recnfiguration

!
configure
        !
        network
                !
                interfaces
                        !
                        bridge 0
                                address 10.0.0.1/24
				!
				! Try to add these subinterfaces
				! after ncsh service startup
				!
                                interface tap0
                                interface tap1
                                !
                                egress tbf
                                      rate 10Mbit
!
events
        netlink

		      

There can be more complex setup, like this — with routing reconfiguration:

Example 24. Netlink events: dynamic routing

!
configure
	! 
	network
		! 
		interfaces
			! 
			! External interface, binded to MAC
			! Through this interface a machine
			! reaches an interoperation network
			! 
			ethernet external
				address 192.168.0.10/24
				hwaddr 00:11:2f:28:69:da
			! 
			! 1.2.3.4 -- IP-address of a VPN-gateway
			! 
			pptp vpn
				host 1.2.3.4
				user pupkin
		! 
		routing
			! 
			! By default, apply routing table
			! from "default" section
			! 
			call default
			! 
			! Catch address add event on
			! VPN session
			! 
			catch netlink.address.add if session=vpn
				! 
				! Apply "ppp" routing table
				! 
				call ppp
			! 
			! Catch address del event on
			! PPP interface
			! 
			catch netlink.address.del if dev=ppp0
				! 
				! Apply "default" routing table
				! 
				call default
			! 
			! Main routing table in the
			! "default" state
			! 
			table main default
				declare
				route default via 192.168.0.128
			! 
			! Main routing table in the
			! "ppp" state
			! 
			table main ppp
				declare
				route 1.2.3.4 via 192.168.0.128
				route default via 10.0.0.1
! 
events
	! 
	! Netlink socket monitor -- it generates events
	! netlink.address.add и netlink.address.del
	! 
	netlink

		      

SNMP events

Ncsh implements SNMP simple trap daemon taht cat use SNMP protocol of version 2c. Here are examples of trap usage:

Example 25. SNMP events: catch linkUp from a device

!
configure
        !
        network
                !
                routing
                        !
                        call default
                        !
                        table main default
                                declare
                                route default via 192.168.0.128
                        !
                        table main bypass
                                declare
                                route 1.2.3.4 via 192.168.0.128
                                route default via 10.0.0.1
!
catch snmp if snmpTrapOID=linkUp if snmpTrapEnterprise=1.3.6.1.4.1.294
        call default
!
catch snmp if snmpTrapOID=linkUp if snmpTrapEnterprise=1.3.6.1.4.1.295
        call bypass
!
events
        !
        ! listen on udp:192.168.0.10:162
        ! 
        snmp 192.168.0.10 port 162
!
		      

Example 26. SNMP events: restart a system service

!
catch snmp if snmpTrapOID=linkUp if snmpTrapEnterprise=1.3.6.1.4.1.294
        exec service pptp restart
!
events
        snmp port 1162
!