unitctl export subcommand

[avahahn]

Currently implemented is a unitctl subcommand that saves Unitd configuration to a tarball. This is the first step in addressing #1317.

Yet to be implemented is support for saving NJS modules or certificates. The code enclosed will be trivial to extend to support that later. Until then, #1317 should remain open.

[lcrilly]

If unitctl import is how configuration gets applied then shouldn't unitctl export be how configuration is retrieved?

Or perhaps that's already planned, and this is a deliberately different thing that is designed for the entire configuration? It's not clear to me what the overall goal of https://github.com/nginx/unit/issues/1317 is.

It would make it much easier to understand the intent of the PR if the commit message/comment had a sample shell snippet with an example unitctl interaction.

[avahahn]

If unitctl import is how configuration gets applied then shouldn't unitctl export be how configuration is retrieved?

Sure, I am happy to rename the subcommand.

It would make it much easier to understand the intent of the PR if the commit message/comment had a sample shell snippet with an example unitctl interaction.

off the top of my head:

# backup configuration
unitctl export -f backup.tar

# restore backed up configuration
tar -xvf backup.tar
unitctl import backup

I am happy to record a small screencap of the above.

[avahahn]

Subcommand is now renamed to export

[lcrilly]

@avahahn this won't work:

# backup configuration
unitctl export -f backup.tar

# restore backed up configuration
tar -xvf backup.tar
unitctl import backup

The /certificates endpoint cannot be imported. Unit won't expose the secrets.

So this might have an impact on the overall design (and value) of this feature.

[avahahn]

The /certificates endpoint cannot be imported. Unit won't expose the secrets.

Sounds like you mean it can't be exported. That is unfortunate but I still believe this is worth implementing at least for configuration and js_modules. I will add a note to the Readme that certificates must be replicated separately.

[lcrilly]

What do you think should happen if an exported configuration contains listeners with tls objects, and that configuration is sent to the import subcommand?

Does this align with your vision for this feature?

# backup configuration
unitctl export -f backup.tar

# take a look
tar tfv backup.tar
drwx------ <uid> <gid>       0 17 Jun  2024 unitd-backup-20240617/
-rw------- <uid> <gid>     502 17 Jun  2024 unitd-backup-20240617/certificates-info-only.json
-rw------- <uid> <gid>    1774 17 Jun  2024 unitd-backup-20240617/config.json
-rw------- <uid> <gid>     256 17 Jun  2024 unitd-backup-20240617/js_modules.json
-rw------- <uid> <gid>     315 17 Jun  2024 unitd-backup-20240617/status.json

import will always destroy and reload the running configuration? importing from a .tar file assumes that the source is an export? Therefore fatal error if listeners have tls objects. Filenames have special meaning, e.g. ignores status.json instead of treating it as more config. importing from a directory might contain .pem files - could we try to match with the certificates JSON to get them loaded?

[avahahn]

What do you think should happen if an exported configuration contains listeners with tls objects, and that configuration is sent to the import subcommand?

Currently import already handles pem files (and js_modules). This MR only saves the configuration JSON. Import will not directly read from a tar file. It is up to the user to extract the tarball and their certificates before importing. This provides a start that addresses at least the second two user stories from the linked ticket.