Make README more consice.

1 files changed, 52 insertions, 315 deletions

diff --git a/README.md b/README.md
index 704551a..bcf3859 100755
--- a/README.md
+++ b/README.md
@@ -1,346 +1,83 @@
-#VyMGMT

-A python library for VyOS configurations

+VyMGMT

+======

 

-This python library is used for VyOS configurations.  

+A python library for executing commands on VyOS systems.

 

-Use this library to send the configuration commands to VyOS. 

+Generic methods should also work with any of the Vyatta descendants (EdgeOS, Brocade vRouter).

 

-##Note

-###Version:0.1 

- 

-###Author:Hochikong  

- 

-###Contact me:hochikong@foxmail.com(usually use) or michellehzg@gmail.com(Inconvenient in Mainland China)  

+The library is compatible with both python2 and python3.

 

-###License:MIT   

-  

-###Requirement:pexpect(pxssh)  

+It is released under the MIT license.

 

-###Platform:Python2 and 3

+## How it works

 

-##Basic Example

-Set a description for eth0:   

+VyMGMT uses pexpect.pxssh library to login to VyOS and execute commands there. This approach has

+its downsides, but it's better than nothing.

 

-    >>> from vymgmt.router  import Router

-	>>> vyos = Router('192.168.225.2','vyos','vyos')

-	>>> vyos.login()

-	>>> vyos.configure()

-	>>> vyos._status()

-	{'session_modified': False, 'logged_in': True, 'session_saved': True, 'conf_mode': True}

-	>>> vyos.set("interfaces ethernet eth0 description 'interface_eth0'")

-	>>> vyos._status()

-	{'session_modified': True, 'logged_in': True, 'session_saved': True, 'conf_mode': True}

-	>>> vyos.logout()

-	Traceback (most recent call last):

-	  File "<stdin>", line 1, in <module>

-	  File "/usr/local/lib/python3.5/dist-packages/vymgmt-0.1-py3.5.egg/vymgmt/router.py", line 90, in logout

-	vymgmt.router.VyOSError: Cannot logout before exiting configuration mode

-	>>> vyos.commit()

-	>>> vyos.exit()

-	Traceback (most recent call last):

-	  File "<stdin>", line 1, in <module>

-	  File "/usr/local/lib/python3.5/dist-packages/vymgmt-0.1-py3.5.egg/vymgmt/router.py", line 174, in exit

-	vymgmt.router.VyOSError: Cannot exit a session with unsaved changes, use force flag to ignore

-	>>> vyos.save()

-	>>> vyos.exit()

-	>>> vyos.logout()

-	>>> vyos._status()

-	{'session_modified': False, 'logged_in': False, 'session_saved': True, 'conf_mode': False}

+Why is it better than using pxssh or another expect library directly?

+To make life easier for the user, it provides methods such as set(), delete(), and commit()

+that detect errors and raise appropriate exceptions when an error occurs.

 

-Because we have save the configuration,so if you reboot the VyOS system but the static router still works.

+## API reference

 

-If you change the configuration,you must commit and save it then you can exit configure mode.But you can use vyos.exit(force=Ture) to execute "exit discard" command. 

+Will be on readthedocs soon.

 

-##Something you should know

-1.Only admin level user can use this library to login and execute all configuration methods.  

+## Installation

 

-2.set() and delete() method is the core function of this library,you can just use a same configuration command on VyOS to set or delete a specify configuration.But you should take a look at the Basic Example and All Methods sections.  

+Will be on PyPI soon.

 

-#Quick Start

-I will show you how to use this library to configuration the VyOS

+## Usage example

 

-The first step is login and configure a interface for management.Look at this example,in this example,I have configure eth0 for vymgmt,and I will show you how to login and configure an interface by this library。

+```

+import vymgmt

 

-Let's check the interfaces.Well,eth1 is the target interface,and we should set a address for this interface:

+vyos = vymgmt.Router('10.217.16.15', 'vyos', password='vyos', port=22)

 

-	vyos@vyos1:~$ show interfaces

-	Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down

-	Interface        IP Address                        S/L  Description

-	---------        ----------                        ---  -----------

-	eth0             192.168.225.2/24                  u/u  

-	eth1             -                                 u/u  

-	eth2             192.168.83.142/24                 u/u  

-	lo               127.0.0.1/8                       u/u  

-	                 ::1/128

+vyos.login()

+vyos.configure()

 

-Let's import the Router and initialize a Router instance:

-	

-	>>> from vymgmt.router import Router

-	>>> vyos1 = Router('192.168.225.2','vyos','vyos')

+vyos.set("protocols static route 203.0.113.0/25 next-hop 192.0.2.20")

+vyos.delete("system options reboot-on-panic")

 

-You should import class Router from vymgmt.router,the use address and "username:password" to initialize the instance.

+vyos.commit()

+vyos.save()

+vyos.exit()

+vyos.logout()

 

-Then,you can use login() to login vyos1:

-	

-	>>> vyos1.login()

+```

 

-If there are no problems,this method will return nothing to user.

+If something goes wrong, an exception is raised and the original error message from VyOS is included in its error string:

 

-By now,you can use configure() and execute configuration commands:

+```

+>>> vyos.set("system foobar true")

+Traceback (most recent call last):

+  File "<stdin>", line 1, in <module>

+  File ".../vymgmt/router.py", line 216, in set

+    raise ConfigError(output)

+vymgmt.router.ConfigError:  set system foobar true

 

-	>>> vyos1.configure()

+  Configuration path: system [foobar] is not valid

+  Set failed

 

-You can use _status() method to get the status of this instance:

+[edit]

 

-	>>> vyos1._status()

-	{'session_modified': False, 'logged_in': True, 'session_saved': True, 'conf_mode': True}

+```

 

-When you login,"logged\_in"'s value will change to True.And now,the value of "conf_mode" is True.

+If you want to execute a command that is not yet supported explicitly, you can use run_op_mode_command() and

+run_conf_mode_command() methods that take a full command and execute it on the other side.

 

-Next,we can use set() to set a address for eth1:

+## Behaviour

 

-	>>> vyos1.set("interfaces ethernet eth1 address '192.168.10.5'")

-	Traceback (most recent call last):

-	  File "<stdin>", line 1, in <module>

-	  File "/usr/local/lib/python3.5/dist-packages/vymgmt-0.1-py3.5.egg/vymgmt/router.py", line 190, in set

-	vymgmt.router.ConfigError:  set interfaces ethernet eth1 address '192.168.10.5'

-	

-	  Invalid IPv4 address/prefix

-  

-	  Value validation failed

-	  Set failed

+All methods raise a VyOSError exception if you try to use them when the Router object is in a wrong state,

+such as trying to run configure() before logging in, or trying to run set() before configure().

 

-	[edit]

-	vyos@test-vyos

+If something goes wrong on the other side, ConfigError or its subclass CommitError is raised.

+One special case, ConfigLocked (a subclass of CommitError) is raised when commit fails because there

+is another commit in progress. It's made a special case because it's the only commit error that can

+be recovered from easily (just wait a bit and retry).

 

-Oh,NO!I just forgot the netmask.But you can see,if your input has mistakes,this library will raise a exception and display the error message to you.Because my configuration lost netmask,therefore the error reason is invalid address.And vymgmt will raise a ConfigError.You can see "Exceptions" section to get more information.

+By default, exit() will not let you exit and will raise a VyOSError is there are uncommited or unsaved changes.

+You can override it with exit(force=True).

 

-Now,let's use a correct configuration:

 

-	>>> vyos1.set("interfaces ethernet eth1 address '192.168.10.5/24'")

 

-Well,I have set the address for eth1 now.

-

-Let's check the status now:

-

-	>>> vyos1._status()

-	{'session_modified': True, 'logged_in': True, 'session_saved': True, 'conf_mode': True}

-

-You can see,"commit" and "save" are "No",so,you must commit and save it.

-

-Commit:

-

-	>>> vyos1.commit()

-

-Save it:

-

-	>>> vyos1.save()

-

-Let's check the status again:

-

-	>>> vyos1.status()

-	{'status': 'login', 'commit': 'Yes', 'save': 'Yes', 'configure': 'Yes'}

-

-You see,the value of "commit" and "save" have changed to "Yes",now I can exit the configure mode and logout.But if you don't commit and save,you still can use "vyos1.exit(force=True)" to exit and discard what you have configured:

-

-	>>> vyos1.exit()

-	>>> vyos1._status()

-	{'session_modified': False, 'logged_in': True, 'session_saved': True, 'conf_mode': False}

-	>>> vyos1.logout()

-	>>> vyos1._status()

-	{'session_modified': False, 'logged_in': False, 'session_saved': True, 'conf_mode': False}

-

-But once you want to login again,you don't need to create a new instance,just use the former instance:

-

-	>>> vyos1.login()

-

-Now,I have configured an ethernet interface by this library,let's check it on vyos1:

-

-	vyos@vyos1:~$ show interfaces

-	Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down

-	Interface        IP Address                        S/L  Description

-	---------        ----------                        ---  -----------

-	eth0             192.168.225.2/24                  u/u  

-	eth1             192.168.10.5/24                   u/u  

-	eth2             192.168.83.142/24                 u/u  

-	lo               127.0.0.1/8                       u/u  

-	                 ::1/128

-

-Now,I will show you how to use set() method to configure a rip router:

-

-Topo:

-

-	test1---VyOS1———VyOS2---test3

-

-The address of test1 is 192.168.225.3,and the address of test3 is 192.168.157.8.Now these two vms can not ping each other.

-

-	root@test1:~# ping -c 5 192.168.157.8

-	PING 192.168.157.8 (192.168.157.8) 56(84) bytes of data.

-

-	--- 192.168.157.8 ping statistics ---

-	5 packets transmitted, 0 received, 100% packet loss, time 4017ms

-

-I have set two test vms' gateway.Now login vyos1,configure the rip network:

-

-	>>> from vymgmt.router import Router

-	>>> vyos1 = Router('192.168.225.2','vyos','vyos')

-	>>> vyos1.login()

-	>>> vyos1.configure()

-

-First,we should add a new lo address:

-

-	>>> vyos1.set("interfaces loopback lo address 1.1.1.1/32")

-

-Then configure rip networks:

-

-	>>> vyos1.set("protocols rip network 192.168.225.0/24")

-	>>> vyos1.set("protocols rip network 192.168.10.0/24")

-

-And the last step:

-

-	>>> vyos1.set("protocols rip redistribute connected")

-

-Sometimes,you may forget to commit or save,the library will raise an exception and refuse to exit:

-

-	>>> vyos1._status()

-	{'session_modified': True, 'logged_in': True, 'session_saved': True, 'conf_mode': True}

-	>>> vyos1.exit()

-	Traceback (most recent call last):

-	  File "<stdin>", line 1, in <module>

-	  File "/usr/local/lib/python3.5/dist-packages/vymgmt-0.1-py3.5.egg/vymgmt/router.py", line 168, in exit

-	vymgmt.router.VyOSError: Cannot exit a session with uncommited changes, use force flag to discard

-	>>> vyos1.save()

-	Traceback (most recent call last):

-	  File "<stdin>", line 1, in <module>

-	  File "/usr/local/lib/python3.5/dist-packages/vymgmt-0.1-py3.5.egg/vymgmt/router.py", line 152, in save

-	vymgmt.router.VyOSError: Cannot save when there are uncommited changes

-

-Therefore,we should execute commit() and save():

-

-	>>> vyos1.commit()

-	>>> vyos1.save()

-

-Then on vyos2,we can configure rip network:

-

-	>>> vyos2 = Router('192.168.10.6','vyos','vyos')

-	>>> vyos2.login()

-	>>> vyos2.configure()

-	>>> vyos2.set("protocols rip network 192.168.10.0/24")

-	>>> vyos2.set("protocols rip network 192.168.157.0/24")

-	>>> vyos2.set("protocols rip redistribute connected")

-	>>> vyos2.commit()

-	>>> vyos2.save()

-

-Then check it on test1:

-

-	root@test1:~# ping 192.168.157.8 -c 5

-	PING 192.168.157.8 (192.168.157.8) 56(84) bytes of data.

-	64 bytes from 192.168.157.8: icmp_seq=1 ttl=62 time=0.947 ms

-	64 bytes from 192.168.157.8: icmp_seq=2 ttl=62 time=1.12 ms

-	64 bytes from 192.168.157.8: icmp_seq=3 ttl=62 time=1.34 ms

-	64 bytes from 192.168.157.8: icmp_seq=4 ttl=62 time=1.37 ms

-	64 bytes from 192.168.157.8: icmp_seq=5 ttl=62 time=1.48 ms

-

-	--- 192.168.157.8 ping statistics ---

-	5 packets transmitted, 5 received, 0% packet loss, time 4009ms

-	rtt min/avg/max/mdev = 0.947/1.255/1.482/0.196 ms

-

-On test3:

-

-	root@test3:~# ping 192.168.225.3 -c 5

-	PING 192.168.225.3 (192.168.225.3) 56(84) bytes of data.

-	64 bytes from 192.168.225.3: icmp_seq=1 ttl=62 time=1.18 ms

-	64 bytes from 192.168.225.3: icmp_seq=2 ttl=62 time=1.38 ms

-	64 bytes from 192.168.225.3: icmp_seq=3 ttl=62 time=1.25 ms

-	64 bytes from 192.168.225.3: icmp_seq=4 ttl=62 time=1.35 ms

-	64 bytes from 192.168.225.3: icmp_seq=5 ttl=62 time=1.03 ms

-

-	--- 192.168.225.3 ping statistics ---

-	5 packets transmitted, 5 received, 0% packet loss, time 4008ms

-	rtt min/avg/max/mdev = 1.036/1.241/1.381/0.127 ms

-

-Now,maybe you are understand how to use this library to configure VyOS. 

- 

-#All Methods

-##_status():

-Check the router object inner status.  

-

-Return a dictionary include the status of Router instance.  

-

-##login():

-Login the VyOS system when you have create a new BasicRouter instance.  

-

-##logout()

-Logout the VyOS system.  

-

-This method execute a close() on a connection.  

-

-You can use this method logout a router substance.After logout,you can use the same instance to login again.  

-

-##configure()

-Enter the VyOS configure mode  

-

-You must login the VyOS system before use this method.  

-

-##commit()

-Commit the configuration changes.  

-

-You can use this method to commit your configuration.  

-

-Due to configuration methods will change the value of the keys in self.__status.You should commit the configurations then can you save or exit.  

-

-##save()

-Save the configuration after commit.  

-

-You can use this method to save your configuration.  

-

-##exit(force=False)

-Exit VyOS configure mode.  

-If you not use "force",you can exit without save but you should commit first or it will raise a exception  

-

-Example:  

-force: True or False  

-

-If force=True,this method will execute "exit discard" command and all your changes will lost.  

-

-##set(config)

-Basic 'set' method,execute the set command in VyOS.

-

-Example:  

-config: "interfaces ethernet eth0 description 'eth0'"

-

-The minimal configuration method.

-

-##delete(config)

-Basic 'delete' method,execute the delete command in VyOS.

-

-Example:  

-config: "interfaces ethernet eth0 description 'eth0'"

-

-The minimal configuration method.

-

-#Exceptions

-##vymgmt.router.VyOSError

-

-This exception class is for most obviously configuration mistakes.  

-

-When this exception raise,the error message from VyOS will displayed.

-

-##vymgmt.router.ConfigError

-

-This exception class is for set/delete failures due to user's wrong input.

-

-When this exception raise,the error message from VyOS will displayed.

-

-##vymgmt.router.CommitError

-

-This exception class is for commit failures and commit conflict.

-

-When this exception raise,the error message from VyOS will displayed.

-

-##vymgmt.router.ConfigLocked

-

-This exception class is for commit() failures due to the commit conflicts when more than one users committing their configurations at the same time.

-

-When this exception raise,the error message from VyOS will displayed.

-