VyOS remote management library for Python

Someone on Facebook rightfully noted that lately there's been more work on the infrastructure than development. This is true, but that work on infrastructure was long overdue and we just had to do it some time. There is even more work on the infrastructure waiting to be done, though it's more directly related to development, like restructuring the package repos.

Anyway, it doesn't mean all development has stopped while we've been working on infrastructure. Today we released a Python library for managing VyOS routers remotely.

Before I get to the details, have a quick example of what using it is like:

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 you want to give it a try, you can install it from PyPI ("pip install vymgmt"), it's compatible with both Python 2.7 and Python 3. You can read the API reference at http://vymgmt.readthedocs.io/en/latest/ or get the source code at https://github.com/vyos/python-vyos-mgmt .

Now to the details. This is not a true remote API, the library connects to VyOS over SSH and sends commands as if it was a user session. Surprisingly, one of the tricky parts was to find an SSH/expect library that can cope with VyOS shell environment well, and is compatible with both 2.7 and 3. All credit for this goes to our contributor who goes by Hochikong, who tried a whole bunch of them, settled with pexpect and wrote a prototype.

How the library is better than using pexpect directly, if it's a rather thin wrapper for it? First, it's definitely more convenient to just call set() or delete() or commit() than to format command strings yourself and take care of the sending and receiving lines.

Second, common error conditions are detected (through simple regex matching) and raise appropriate exceptions such as ConfigError (for set/delete failures) or CommitError for commit errors. There's also a special ConfigLocked exception (a subclass of CommitError) that is raised when commit fails due to another commit in progress, so you can recover from it by sleep() and retry. This may seem uncommon, but people who use VRRP transition scripts and the like on VyOS already reported that they ran into it.

Third, the library is aware of the state machine of VyOS sessions, and will not let you accidentally do wrong things such as trying to enter set/delete commands before entering the conf mode. By default it also doesn't let you exit configure sessions if there are uncommited or unsaved changes, though you can override it. If a timeout occursm an exception will be raised too (while pexpect returns False in this case).

Right now it only supports set, delete, and commit, of all high level methods. This should be enough for the start, but if you want something else, there are generic methods for running op and conf mode commands (run_op_mode_command() and run_conf_mode_command() respectively). We are not sure what people want most, so what we implement depends on your requests ans suggestions (and pull requests of course!). Other things that are planned but that aren't there yet are SSH public key auth and top level words other than set and delete (rename, copy etc.). We are not sure if commit-confirm is really friendly to programmatic access, but if you have any ideas how to handle it, share with us.

On an unrelated note, syncer and his graphics designer friend made a design for VyOS t-shirts. If anyone buys that stuff, the funds will be used for the project needs. The base cost is around 20 eur, but you can get them with 15% discount by using VYOSMGTLIB promo code: https://teespring.com/stores/vyos?source=blog&pr=VYOSMGTLIB

The new website is now live

Hi everyone,

The new website is now live. There are still some rough edges (typos, odd links, odd wording etc.), if you find anything like this, let us know. But overall it does what it's supposed to do, tells newcomers what VyOS is and provides quick links to downloads and other resources to existing users.

Here's an explanation of what happened exactly. Before that, vyos.net and vyos.org were pointing at the wiki host, and the wiki main page used to serve as our primary website. It means there are quite a few links like http://vyos.net/wiki/Something on the net, and simply pointing that domain at the host with the new website would create quite some link rot.

To avoid this, we've setup two conditional redirects, one redirects vyos.net/wiki/Something to wiki.vyos.net/wiki/Something, another one redirects everything else to vyos.io. So far it seems to work properly, but if you notice any issues with it, such as links that are not redirected correctly, let us know.

P.S. we added some merch(not much but we will add more soon) to our store, please check out https://teespring.com/stores/vyos

wiki.vyos.net now uses the new recaptcha (meaning: way easier to edit)

Hi everyone,

I like to joke about "wiki.vyos.net, a free encyclopedia no one bothers to edit", but there was a thing that actually made it rather inconvenient to edit for people, regardless of their willingness to edit it.

I mean the subnet captcha. If you haven't seen it, it made you calculate a broadcast address of a random subnet to register an account or edit a page. Everyone hated it, including me, and I had to add a number of active editors to a group that is exempt from it, by hand, so that it doesn't keep haunting them.

What's worse is that after a MediaWiki update it stopped working for a mysterious reason which I couldn't quickly debug, so I thought it may be a good time to reconsider it. Now there's the new reCAPTCHA instead, the one that wants you to click an "I'm not a robot" checkbox. For most users, it is trivial to solve, and it proved fairly effective at mitigating spam, so I think at least for now it may be the best solution for everyone.

Still, it's not entirely without controversy. There still may be accessibility converns and, since it's a third-party service, privacy concerns. If the captcha is giving you troubles, we still may make you exempt from it if you tell us your account and explain the issue.

If you, luckily for you, haven't seen the introduction of the subnet captcha, the story was that the wiki (a Vyatta wiki  back then, vyattawiki.net) had all its content replaced with spam overnight, and the original reCAPTCHA did nothing to protect it. We had been having spam problems for a long time by that moment, and after that event, we thought we have to come up with something that will stop spam forever, and so I wrote the subnet captcha plugin, and it worked very well. Except making edits inconvenient for legitimate users of course. Now when it's gone, I hope we'll be getting more editors.

I hope more people will come and edit some pages. We are seriously lacking in the documentation department, but if everyone does a small bit, it's not really that hard. You don't need to write big chunks at once and document complete features, a brief description and a config example is a lot better than nothing.

vyos.net → wiki.vyos.net redirect

You may have noticed (or will notice soon) that http://vyos.net redirects to http://wiki.vyos.net. Don't worry, this is normal.

It's the first step in preparation to roll out the new website. When it goes live, the vyos.net and vyos.io domains will point to the new website, and the wiki will live on its own wiki.vyos.(net|io) domain.

Meanwhile you can view the future website at http://vyos.io/ and give us your feedback, if you haven't already.


dead.vyos.net and contributing to VyOS

Hi everyone,

This is a bit embarassing. For almost a day http://www.vyos.net (but not http://vyos.net) was sending people to the http://dead.vyos.net website, until someone on the IRC pointed it out (thanks for this!).

It happened due to an oddity in the way Apache HTTPD handles host aliases, and it's fixed now.

The dead.vyos.net website was created as a joke for giving the link to people who ask if VyOS project is dead. While the website is indeed a joke, the issue with lack of contributors is very real, and it does slow things down.

If you want to contribute to VyOS, there is a lot of work to be done, and the maintainers on the IRC and in phabricator will be happy to point you to beginner-friendly tasks and answer questions about the code and the patch submission process.