Command line utility

netjsonconfig ships a command line utility that can be used from the interactive shell, bash scripts or other programming languages.

Check out the available options yourself with:

$ netjsonconfig --help
usage: netjsonconfig [-h] [--config CONFIG]
                 [--templates [TEMPLATES [TEMPLATES ...]]]
                 [--native NATIVE] --backend {openwrt,openwisp,openvpn}
                 --method {render,generate,write,validate,json}
                 [--args [ARGS [ARGS ...]]] [--verbose] [--version]

Converts a NetJSON DeviceConfiguration object to native router configurations.
Exhaustive documentation is available at: http://netjsonconfig.openwisp.org/

optional arguments:
  -h, --help            show this help message and exit

input:
  --config CONFIG, -c CONFIG
                        config file or string, must be valid NetJSON
                        DeviceConfiguration
  --templates [TEMPLATES [TEMPLATES ...]], -t [TEMPLATES [TEMPLATES ...]]
                        list of template config files or strings separated by
                        space
  --native NATIVE, -n NATIVE
                        path to native configuration file or archive

output:
  --backend {openwrt,openwisp,openvpn}, -b {openwrt,openwisp,openvpn}
                        Configuration backend
  --method {render,generate,write,validate,json}, -m {render,generate,write,validate,json}
                        Backend method to use. "render" returns the
                        configuration in text format; "generate" returns a
                        tar.gz archive as output; "write" is like generate but
                        writes to disk; "validate" validates the combination
                        of config and templates passed in input;
                        "json" returns NetJSON output:
  --args [ARGS [ARGS ...]], -a [ARGS [ARGS ...]]
                        Optional arguments that can be passed to methods

debug:
  --verbose             verbose output
  --version, -v         show program's version number and exit

Here’s the common use cases explained:

# generate tar.gz from a NetJSON DeviceConfiguration object and save its output to a file
netjsonconfig --config config.json --backend openwrt --method generate > config.tar.gz

# convert an OpenWrt tar.gz to NetJSON and print to standard output (with 4 space indentation)
netjsonconfig --native config.tar.gz --backend openwrt --method json -a indent="    "

# use write configuration archive to disk in /tmp/routerA.tar.gz
netjsonconfig --config config.json --backend openwrt --method write --args name=routerA path=/tmp/

# see output of OpenWrt render method
netjsonconfig --config config.json --backend openwrt --method render

# same as previous but exclude additional files
netjsonconfig --config config.json --backend openwrt --method render --args files=0

# validate the config.json file against the openwrt backend
netjsonconfig --config config.json --backend openwrt --method validate

# abbreviated options
netjsonconfig -c config.json -b openwrt -m render -a files=0

# passing a JSON string instead of a file path
netjsonconfig -c '{"general": { "hostname": "example" }}' -b openwrt -m render

Using templates:

netjsonconfig -c config.json -t template1.json template2.json -b openwrt -m render

# validate the result of merging config.json, template1.json and template2.json
# against the openwrt backend schema
netjsonconfig -c config.json -t template1.json template2.json -b openwrt -m validate

Environment variables

Environment variables are automatically passed to the context argument (if you don’t know what this argument does please read “Context (configuration variables)”), therefore you can reference environment variables inside configurations and templates:

export HOSTNAME=freedom
netjsonconfig -c '{"general": { "hostname": "{{ HOSTNAME }}" }}' -b openwrt -m render

You can also avoid using export and write everything in a one line command:

PORT=2009; netjsonconfig -c config.json -t template1.json -b openwrt -m render