
== Ncsh usage ==

== Description ==

Ncsh is a network configuration system implemented as Connexion-based application.
It consists of two major parts:

1. Connexion instance with modules that provides runtime reconfiguration, events management, etc.

2. management shell - standart Connexion shell connexion-cli that talks to the Connexion instance.
   Through the shell a user can configure the Linux network subsystem, save or load configurations.
   The shell offers simple syntax and easy command autocompletion.

It is not just a static edit-conf-and-restart system: with the management shell you can change and 
apply a part of configuration tree without requirements to restart a whole service.

== Quick start ==

1. Check Connexion instances which will be loaded. Connexion reads instances names from /etc/sysconfig/connexion.
   By default connexion-cli tries to connect to an instance mentioned first, so ncsh instance must be
   first or parameter -s /var/run/connexion/ncsh-socket must be used.

2. Check initial config. Ncsh uses /etc/connexion/ncsh/tree as the only configuration file. You may
   want to convert existing network configuratin with command connexion-ncsh-atodetect and check 
   it with a text editor before running system service. Please, use uniform indentation
   in all config. So, it is an error to mix tabs and spaces indentation.

3. Start the service with command service connexion start.

4. Run management shell with command connexion-cli.

== Shell Usage ==

If  you are not familiar with connecxion-cli, use TAB or ? keys to get autocompletion list. All
commands forms a tree, and some of them can change your state (in bash, it would be "working 
directory"). The current state is displayed in the command prompt, so you can see, where it is 
on the tree.

To change the state one level up (cd .. in terms of bash), you can use command pop or indentation.
Yes, the config (/etc/connexion/config) is just a script for this shell. To leave the shell, 
use keys Ctrl-Q or command quit.

== Ncsh examples ==

See examples in the connexion-doc package. Short examples:

{{{
# create IPv4 address on an interface
ncsh > configure network interfaces ethernet 0
ethernet 0 > address 10.0.0.1/24
ethernet 0 > commit

# remove IPv4 address from an interface
ncsh > configure network interfaces ethernet 0
ethernet 0 > no address 10.0.0.1/24
ethernet 0 > commit

# create VLAN 101 interface (way #1)
ncsh > configure network interfaces ethernet 0.101
        # setup inteface
ethernet 0 > commit

# create VLAN 101 interface (way #2)
ncsh > configure network interfaces ethernet 0
ethernet 0 > vlan 101
        # setup interface
vlan 101 > commit

# create a route
ncsh > configure network routing table
table > route default via 10.0.0.1
table > commit

# remove a route
ncsh > configure network routing table
table > no route default via 10.0.0.1
table > commit

# see actual configuration: tree
ncsh > tree
!
configure
        !
        network
                ...

# see pending changes: transaction
ncsh > transaction
!
configure
        !
        network
                ...

# jump to root context: pop /
ncsh > configure network interfaces ethernet 0
ethernet 0 > vlan 101
vlan 101 > pop /
ncsh >
}}}