Automating config - best practice?

I've been looking at ways to automate device config. It started with wanting to have a default config, which naturally led to guidance about defaults and about bulk config of devices, but that leads me to this question.

What's the benefit of using the uci CLI for automating config, over replacing config files via SSH?

To elaborate a little, I'm thinking that it might be useful to have all config files in a git repository (probably on GitHub, FWIW) and then using those version-controlled files as a default config, for backups, and for the purposes of generally ensuring good cleanliness.

From the official guidance on uci, it mentions that the uci CLI more or less just makes changes to the underlying config files.

I'm also vaguely imagining that it might be good to use Ansible or something, for the actual automation, but that's probably a detail at this point.

So, again, the question is, is there a benefit to having a script that makes changes via the CLI, vs. having a script (or whatever) that gets and replaces complete config files (and runs restarts, etc., of course)?

You can’t have illegal or non existing variables in a script with uci code since you will get errors when running the script. So there is no accumulating old scrap buildup if you don’t reuse old configs.

And we have these situations with old non functional reused configs over and over again here at the forum. Especially obvious after big changes like moving from swconfig to dsa.

1 Like

That's a great point, thank you. I've not been using OpenWRT for long enough to have had that problem myself, but I can imagine!

Quick follow-up: would such a CLI-based script, then, replace all types of back up, in your mind? Or would you also take regular back-ups?

Thinking about it, I suspect using the CLI might make it easier to take a more DRY approach to things too - rather than building several config files on the fly based on additional config files with variables stored in them, for example.

Another advantage of using the uci cli is that you can amend default configs instead of blindly replacing them. This might matter since each device model uses a different default configuration (network interface amount and names vary; amount, supported bands and identity of wireless radios might differ etc.)

Using uci will make it easy to extract relevant values from configs, instead of e.g. awk/sed/grep scripting.

If configuration changes consist solely of uci operations, it might even be possible to use the uci over ubus over HTP api which LuCI uses.


Backup is really another question and that usually includes a lot of other things and files other than the config files and how fast you need to get up and running again.

I have a “development router” that I use to develop the script that have about 1300-lines nowadays.
So the operational router isn’t really exposed for trial and error.

1 Like

Thanks both - that's most useful :+1: Consider me convinced that I should use the CLI tool.

Feels like it's going to be a bit painful to convert the config files into a bunch of statements, but I'm sure it'll be worth it in the end!

There is a good template on github to begin with. You will find it if you google.

And start small scale and get at least one config working and expand from that.

And many times luci gives you many answers if you make a change and only save and then take a look at the pending change menu at the top.

And use uci show <config name> to get the ID number of the config lines.
And remember that a bunch of firewall rules for example need to be removed from the last number first or else all other rules change ID number.

In addition to comments by @flygarn12 and @jow -- if you have a shell script which configures your router(s) you may also want to use it as the uci-defaults script and build your own images (with the WebUI firmware builder or using an Image Builder in a Linux VM) which will contain all your settings as soon as router boots up.

Once you have the configuration script working, making a custom image with it as uci-defaults script is quite an easy step with the huge quality of life improvement.

Just make sure to update the script if you make any changes to your running router. :wink:


I've been researching for my next wire router. Will be an upgrade to Edgerouter X which I've been running 24/7 for eight years. After all options (hardware/software) considered, I think I'll end up running OpenWRT on the new yet to be purchased router. Hence, I've done brief study of uci.

One very neat feature of Edgerouter X (or essentially Vyatta middleware) is that the whole system configurations are consolidated into a single human-readable text file. After each firmware update/upgrade, the middleware will automatically generate from the single config file into application-specific configuration files.

After my brief study of uci, I found the concept here is very similar. The main difference seems to be: instead of a single human-readable config file, uci will store in several files residing in /etc/config. And from there, uci middleware will generate application-specific configuration files.

So I'm here seeking some best practices of uci too.

From what I read so far, it seems a good idea to

  1. consolidate all uci setup instructions into a single script file
  2. run the script after OpenWRT (vanilla image not custom image) upgrade & reboot; so instantly restore system configuration to what I've previously setup.

Is this understanding correct? Also, is there any facilities/hooks in OpenWRT that will run the single uci script file on the first reboot after OpenWRT image upgrade?

What gurus will preach to a new but geeky user about uci best practices?


Yes, there is the uci-default system where you build the image with this file in a folder.

There is one thing to keep in mind though when using uci-defaults since that comes with no turning back once initiated. If you have a system failure fault in the script you are in trouble because you can never get a working system (maybe not even a way to connect to the router without serial) what ever you do.
If you instead install a default image and run a script with a fault you can simply reset and redo.

But if you want to use uci-defaults it is probably simpler to just use the config files right away instead of using a script run by uci-defaults at first boot.

The only thing I use uci-default to is make really basic settings at first boot like timezone which is really nice but it isn’t a dealbreaker.
When I had the realtek switch I also used to set it to dhcp client and set up a tagged vlan at first boot so I at least was able to connect to it to run the big setup script.

And if you want any extra packages these need to be installed at build time or at least before running the script if the script have commands for those extra packages.

1 Like