vyTool/vyInstall HOWTO

What is vyTool/vyInstall all about?

vyTool/vyInstall is a couple of utilities designed to ease administration of Vyatta systems.
With many routers, it is a real pain to do manually same recurring tasks again and again.
Think. It is the waste of your time, waste of your efforts and finally waste of your life.
So… Why not automate some routines? 😉

vyTool is Vyatta config(config.boot), OpenSSL keypair(certificate + private key),
CA/CRL and SSH keyring(public key collection) generation and management tool.
config.boot files are generated from pre-defined samples(templates) and then encrypted.
Admin generates config for any use case with only few needed parameters specified.
OpenSSL certificates and private keys are generated using built-in CA,
private keys are encrypted. CRLs are also managed with built-in CA.
vyTool must be installed on some kind of secure central server.
It may be Vyatta(recommended), Debian or even Ubuntu environment,
which will NOT serve as a router, but will serve as a dedicated configuration storage.
Consider an isolated KVM/Xen/VMware VM with public access to web server ONLY.
Web server, e.g. Apache will be used to publish generated configurations, certificates, etc.
Think about vyTool as about server software.
You will probably need only one server with vyTool installed.

vyInstall is Vyatta config, OpenSSL keypair and SSH keyring installation tool.
This must be installed on routers. Think about it as about client software.
vyInstall connects to server running vyTool through HTTP(S) and downloads
encrypted configs, OpenSSL keypairs(private key encrypted), SSH keyrings,
CA certificates and CRLs.
You will need to install vyInstall on every router you want to manage with vyTool.


Please do not use this HOWTOs on already working production environment!

Following HOWTOs are for Vyatta users with some solid experience.
Users with little or no Vyatta experience are advised to configure
few systems manually before using vyTool/vyInstall.

Download and install VC6.1 on a separate dedicated server or VM(recommended).
I personally use Vyatta with Linux KVM and very pleased about it in all aspects.
Add Vyatta4People.Org package repository:
set system package repository vyatta4people url http://packages.vyatta4people.org/debian
set system package repository vyatta4people distribution experimental
set system package repository vyatta4people components main
sudo apt-get update

Install vytool:
sudo apt-get install vytool

Prepare lighttpd to serve requests to vyTool data directory.
Edit /etc/lighttpd/lighttpd.conf, change line 30 to:
server.document-root = "/var/lib/vytool"

Activate lighttpd, if it is turned off:
set service https

or just restart, if lighttpd is already on:
sudo /etc/init.d/lighttpd restart
lighttpd on vyTool server will now serve requests to vyTool data ONLY.
It will not be easily possible and highly undesirable to use it for any other purpose,
because of security and clarity reasons.

Grab pre-created sample from Vyatta4People.Org website:
sudo wget --no-check-certificate -O /etc/vytool/config-samples/SimpleRouter.sample https://github.com/vyatta4people/vyTool/raw/master/SimpleRouter.sample

Generate bundle(config+openssl keypair):
sudo vytool create-bundle SimpleRouter rt01 --domain-name=company.com --lan-id=22

You will see something like this:
[ rt01 ]
Config/OpenSSL private key bundle password: jRrZBCij

Congratulations, you’ve just created a Vyatta configuration
with corresponding OpenSSL certificate and private key pair!

Log in our your target router, where you want to install
new configuration and OpenSSL stuff.

Add Vyatta4People.Org package repository:
set system package repository vyatta4people url http://packages.vyatta4people.org/debian
set system package repository vyatta4people distribution experimental
set system package repository vyatta4people components main
sudo apt-get update

Install vyInstall:
sudo apt-get install vyinstall

Edit file /etc/default/vyinstall, set address of your vyTool server:

Use vyInstall to install generated config.boot and OpenSSL stuff:
sudo vyinstall openssl-ca
sudo vyinstall bundle rt01 jRrZBCij
sudo reboot

HINT: Your host-name and password will be different from “rt01” and “jRrZBCi”.
HINT: Reboot is not necessary, you may just issue “load” command in configuration mode.

Login to your router after reboot and you will see your router now serving subnet on eth0, NTP server is set to, etc…
Note some firewall and QoS rules already included. Yes, this is it,
EVERYTHING may be included in config sample(template),
with tweakable parameters presented as %(parameter).
Please look at the SimpleRouter.sample file to get more understanding.

vyTool/vyInstall couple can do 2 more things besides just generating
configs and OpenSSL key pairs. It can manage OpenSSL certificate
revocation list (CRL) and SSH public keyrings.

vyTool CRL management is automatic, adding certificate to CRL
happens after execution of “sudo vytool destroy-openssl-keypair …”.
To update CRL on client just issue “sudo vyinstall openssl-crl”,
this command may also be added to crontab.

To create SSH keyrings you must first populate directory
/etc/vytool/ssh-keys on vyTool server with *.pub files (SSH public keys).
e.g. you have public keys kenny.pub and kyle.pub in /etc/vytool/ssh-keys,
just issue keyring generation command on vyTool server:
sudo vytool create-ssh-keyring default kenny kyle
and then issue on router:
sudo vyinstall ssh-keyring default
Voila! Passwordless logins are working!

For now that’s all. 🙂
Project just started, expect active development and nearly everyday updates.
Hope to improve config.boot validation and create sane manual ASAP.
Would like to hear your feedback.
Your opinion, suggestions and comments are very important.

Thanks for your attention!

NB! vyatta login password for default config sample is 1234.

This entry was posted in Vyatta and tagged . Bookmark the permalink.

30 Responses to vyTool/vyInstall HOWTO

  1. cR0n says:

    nice work, but you should add video tutorials!

  2. Hi Cartman,
    Looks like a good beginning. In future versions would be nice to have possibility to store values for end configurations in file as key-value pairs and automatically generate the config by requests from vyInstall containing a “router identifier”.

  3. Pierre Orsini says:

    Bien fait. Bonne chance!

  4. openredes says:

    Nice job!
    At the moment I have 60 Vyatta boxes on a production environment and would be excelent to could use your utilities. I had to find time to do a checking…

  5. Ülo says:

    Nice project!
    But where are the manuals? 😉

  6. xDuke says:

    Solid piece of software. Works like champ on my VC 6.1 boxes.
    But will you support VC 5.0.2?

    Anyway thanks!

  7. adieball says:

    Cartman, some changes need to be done. Since V6.3 there is a new directory structure to use if you want your config stuff to survive new image installations:

    This release changes the location for storing some configuration information and files on which features in the configuration depend. (The location of the /config directory itself has not changed.) This change has been made to provide a consistent, standard location for configuration information, to improve the user experience and simplify upgrade, and to reduce the likelihood of configuration errors during upgrade. The /config directory now has the following subdirectories:
     archive – Existed previously; no change. Archive directory for configuration changes. Used by the configuration management function.
     auth – New. Stores security certificates.
     ips – New. Stores IPS rules and other IPS data on which content-inspection
    configuration depends.
     scripts – New. Stores scripts referenced from within the CLI (for example, VRRP transition scripts).
     support – New. Stores information generated when the show tech-support command is issued.
     url-filtering – New. Stores the URL-filtering database and other data on which URL- filtering configuration depends.
     user-data – New. Stores user-generated scripts and user data. Use this directory as the single place for keeping all files you want to preserve across images.
    More details about the new structure of configuration information can be found in the “Working with Configuration” chapter of the Vyatta Basic System Reference Guide.
    Preserving configuration of some features during upgrade to this release requires a migration procedure. See the “Upgrade Notes” section for this information.


    This is for the subscription edition right now, but the Core Edition will have the same I assume ….

  8. Cartman says:

    Thanks for notice, adieball!

    But to make any changes I need an installation of Vyatta 6.3 to play with.
    Are there any legal ways to obtain 6.3 without being a subscriber? 🙂

  9. Amos Botto says:

    Great tutorial just did the whole setup tonight by myself. I must say its a real eye opener to the way we install and configure vyatta routers. Kudos!

    However, just rebooted my router and I cant login. What username and password should I use? Please help?

  10. Cartman says:

    Hi Amos!

    Did you use password “vyatta” or “1234”?
    If they both are not suitable, please tell what config-sample did you use?

    Looking forward to hearing from you!
    I plan to update Config-Validator and vyTool/vyInstall,
    so any feedback is extremely welcome. 🙂

    • Amos Botto says:

      Hi is used vyatta. However I created another rt02 with lan id 23. I missed out the ca key that was created in the first rt01, so thats why i made a second config file.

  11. Amos Botto says:

    Oh i see the 1234 works. Thanks a million….

    • Cartman says:

      Glad it’s OK now!
      Wish you troubleless vyTool usage and
      great experience with Vyatta in general. 🙂

      If you got any questions, you are welcome here.

  12. Hank says:


    I tried to add ssh public/private key pair and I get “private key is invalid or unsupported” message.
    Are you aware any bug that should be fixed to be able to enter the private key?


  13. Hank says:


    I tried to follow this document:

    If you need screenshot I can do it in a few days.

  14. Cartman says:

    Oh! You are talking about vyBuddy… 🙂
    Maybe this will help:
    Filled private key form should look like this:

    NB! Private key MUST NOT be encrypted!

    Please keep me informed about your results.

  15. Hank says:

    Ok. The encryption is the problem.
    my key file starting like this:
    Proc-Type: 4,ENCRYPTED
    DEK-Info: AES-128-

    The method which is described in the document is going to create an encrypted key, however, I need an unencrypted.
    According to what I have found the ssh-keygen -y is able to decript it, so I did but no success. Not sure how to create a key which is accepted by vybuddy…
    After I run the ssh-keygen -y the result begining like this:
    ssh-rsa AAAAB3NzaC1yc2EA

    Sorry, I’m new with this key pairs and probably I missed something in the mentioned document (http://www.vyatta4people.org/wp-content/uploads/vyBuddy_Appliance_QuickStart_EN.pdf)

  16. Hank says:

    Never mind. Need to keep the passphrase empty and it will not be encrypted.

  17. Hank says:

    Thanks for the help. 🙂

  18. Patrick says:

    Great tool, thanks for sharing it!

    I have vytool/vyinstall working, per your instructions. It’s unclear to me, though, how the process works for config updates. The first (create-bundle) yields an openssl-keypair and an encrypted config, which I’m able to install on the target. Then, in order to make a change I’m trying:
    1) edit sample file
    2) destroy-config
    3) create-config

    The config gets created fine, but I get “Failed to decrypt downloaded file. Wrong password?” when I try to install it on the target.

    If I also destroy-openssl-keypair (and then create-bundle instead of create-config), it works, but I suspect that’s not the correct work-flow (or is it?).

    What’s the correct strategy for editing samples and updating configs?


    • Cartman says:

      Nice to hear your feedback, Patrick!

      Configs and OpenSSL keypairs are encrypted separately,
      so there should be no problem to use them as you try to.

      Please check, if you are using “vyinstall bundle” to get new config,
      and getting errors because of “vyinstall bundle” trying to get also
      OpenSSL keypair with a new password, which of course works only
      for a new config. Use “vyinstall config” to get configs without SSL.
      If you get same errors with “vyinstall config”, please let me know 🙂

      Thanks and good luck!

  19. Patrick says:

    Is there a description of partials somewhere? My use case is that most of my vyatta servers get the same config, but a couple of them have additional things turned on. Is there a way to use partials to compose samples, instead of having to make sure that the majority of 2 samples are identical?

    • Cartman says:

      Partials are not used to create samples, but they are used
      for extending configurations of already running routers.

      If most of your routers are identical, you should have only one sample,
      to create configs from and you may extend running routers with partials.

      Partial is no more than just a part of config file to be merged
      with running router configuration. You place partial in directory
      Name it like something.partial and then run
      vyinstall config-partial something
      on your router.

      Example partial is here:

      BTW do you use variable paramerers like %(domain-name) in
      config samples? They can also make config creation much easier! 🙂

      • Patrick says:

        Thanks for the info. Partials sound interesting, but don’t meet my needs (I like the *.sample strategy of controlling the entire config, but I want to be able to compose partials together to limit duplication). I’ll just add a different template system (ERb or somesuch), to generate my samples.

        For instance, I have two environments with almost identical configs. One environment, though, needs to have an extra static route, and a couple other differences. As I understand it, this is beyond what the existing parameters can give.

        • Cartman says:

          Got your idea, Patrick, but have no such functionality for now.
          I’ll try to implement something like this in next release of vyBuddy,
          which will merge most functionality of my current command line tools.

  20. Chad says:

    Running Vyatta Core 6.6 at it seems that “vyinstall” requires wget to be installed as a standalone package but wget is now part of another package. Any suggestions?

    root@vyatta:/etc/apt# apt-get install vyinstall
    Reading package lists… Done
    Building dependency tree
    Reading state information… Done
    Some packages could not be installed. This may mean that you have
    requested an impossible situation or if you are using the unstable
    distribution that some required packages have not yet been created
    or been moved out of Incoming.
    The following information may help to resolve the situation:

    The following packages have unmet dependencies:
    vyinstall : Depends: wget but it is not installable
    E: Broken packages