summaryrefslogtreecommitdiff
path: root/README.md
blob: 9492231ab01df6b6e72c9dd9b681fdf79be3ef24 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
VyMGMT
======

A python library for executing commands on VyOS systems.

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

The library is compatible with both python2 and python3.

It is released under the MIT license.

## How it works

VyMGMT uses pexpect.pxssh library to login to VyOS and execute commands there. This approach has
its downsides, but it's better than nothing.

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.

## API reference

...is kept on ReadTheDocs. http://vymgmt.readthedocs.io

## Installation

The easiest way is to install from PyPI (https://pypi.python.org/pypi):

```
pip install vymgmt
```

Alternatively you can run the setup.py script to install it locally.

## Usage example

```
import vymgmt

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

vyos.login()
vyos.configure()

vyos.set("protocols static route 203.0.113.0/25 next-hop 192.0.2.20")
vyos.delete("system options reboot-on-panic")

vyos.commit()
vyos.save()
vyos.exit()
vyos.logout()

```

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

```
>>> 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

  Configuration path: system [foobar] is not valid
  Set failed

[edit]

```

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.

## Behaviour

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().

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).

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).

## Credits

This library was originally written by Hochikong (hochikong@foxmail.com (preferred), or michellehzg@gmail.com),
and is now maintained by the VyOS project.