Table of Contents
List of Examples
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].
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.
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
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.
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.
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 — 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
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
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
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
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
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
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
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 filtering controls are implemented only in rudimentary mode. Only basic capabilities are supported, and only with binding to an interface.
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
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
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
One of the important ncsh capabilities is event handling. Now there are two event providers.
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
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 !