From 64882add57a609468e373a2b384d11d06067469f Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Tue, 6 Sep 2016 11:43:47 +0600 Subject: Make README more consice. --- README.md | 367 +++++++++----------------------------------------------------- 1 file 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 "", line 1, in - 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 "", line 1, in - 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 "", line 1, in + 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 "", line 1, in - 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 "", line 1, in - 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 "", line 1, in - 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. - -- cgit v1.2.3