What this module does #
Every time you spin up a server you have to get the baseline in place: install the pending updates, decide the language the programs speak, set the correct time zone, give the machine a name and make sure the clock is on time. They are small but repetitive tasks, and each one has its own Linux command with its own syntax.
The os module brings them all together behind a coherent interface. It updates the system (or just the security portion) and tells you whether a reboot is needed; it enables unattended upgrades so security updates get applied on their own; it sets the locale, the time zone and the hostname idempotently; and it manages NTP synchronization so the time never drifts. Every action is safe to repeat: if it is already in the desired state, it touches nothing.
The subcommands that change something (update, set locale, time zone, hostname or NTP) write to the system and need root privileges: run them with sudo. The ones that only query (status, list, check) do not require it.
Common tasks #
Pick what you want to do. Each recipe comes with the command already written — just swap the example values for your own and hit Copy.
1
View and apply updates
Check what's pending and get up to date in no time.
First look at the overall status and which updates are waiting:
$ imaxe os status
$ imaxe os checkApply what's pending. If you only want the security ones and want it to reboot if needed, add the flags:
$ sudo imaxe os update --security-only --reboot-if-neededimaxe os reboot-required (exit code 0 = yes, it's needed).2
Put security updates on autopilot
Let security updates apply on their own, without you having to watch over them.
Enable unattended upgrades. This generates the unattended-upgrades configuration for you:
$ sudo imaxe os autoupdate enableConfirm that it is active and when the next run will be:
$ imaxe os autoupdate statussudo imaxe os autoupdate disable.3
Set the time zone and time
Set your IANA zone and make sure the clock synchronizes over NTP.
If you don't remember the exact name of your zone, filter it first:
$ imaxe os timezone list EuropeSet the zone (it's idempotent) and enable time synchronization:
$ sudo imaxe os timezone set Europe/Madrid
$ sudo imaxe os timesync enableimaxe os timesync status.4
Set the system language
Define the LANG and generate the locale if it doesn't exist yet.
Set the system language. The command generates the locale and installs the locales package if it's missing:
$ sudo imaxe os locale set es_ES.UTF-8Need more languages available without changing the LANG? Generate them separately:
$ sudo imaxe os locale generate es_ES.UTF-8 en_US.UTF-8imaxe os locale status.5
Change the machine name
Set a clear hostname and keep /etc/hosts consistent.
/etc/hosts consistent.Assign the hostname. Only letters, numbers and hyphens are allowed, up to 63 characters:
$ sudo imaxe os hostname set web-01/etc/hosts is updated to match. Verify it with imaxe os hostname status.If the instance is managed by cloud-init, it may rewrite the hostname on every boot. That's why os.yml leaves the hostname field empty by default: set it only if you know cloud-init won't overwrite it.
Synopsis #
imaxe os <subcomando> [<acción>] [<argumento>...] [flags]The subcommands that change the system (update, unattended upgrades, locale, time zone, hostname, NTP) require root privileges (use sudo). Add --json to any status or check to get machine-readable output, suitable for scripting.
Subcommands #
| Subcommand | What it does | Actions / flags |
|---|---|---|
| status | Summary of the system update status. | --json |
| update | Applies the pending updates now. | --security-only, --reboot-if-needed |
| check | Lists the pending updates without applying them. | --json |
| reboot-required | Indicates whether a reboot is pending (exit 0 = yes, 1 = no). | --json |
| autoupdate | Manages the unattended automatic updates. | enable · disable · status |
| locale | Manages the system locale (generates and installs what's needed). | status · list · set · generate |
| timezone | Shows or changes the system time zone. | status · list · set |
| hostname | Shows or changes the hostname (consistent with /etc/hosts). | status · set |
| timesync | Manages time synchronization (NTP). | status · enable · disable |
Arguments and flags #
| Argument / flag | Type | Where it applies | Description |
|---|---|---|---|
| --json | bool | status · check | Emits the result as structured JSON on stdout, suitable for scripting. |
| --security-only | bool | update | Applies only the security updates. |
| --reboot-if-needed | bool | update | Automatically reboots if the system requires it after updating. |
| <locale> req. | string… | locale set · locale generate | Locale in es_ES.UTF-8 format. In set it's a single one (the system LANG); in generate, one or more to generate. |
| <zona> req. | string | timezone set | IANA time zone, e.g. Europe/Madrid. |
| <filtro> | string | timezone list | Optional filter to narrow down the zone listing (e.g. Europe). |
| <nuevo> req. | string | hostname set | New hostname: lowercase a-z, digits 0-9 and hyphens, maximum 63 characters. |
Files and paths #
| Path | Contents |
|---|---|
| /etc/imaxe/os.yml | Module configuration: unattended upgrades, update policy, locale, time zone, hostname and NTP. |
| /var/log/imaxe/os.log | Structured log of every update and system configuration change. |
| /etc/apt/apt.conf.d/20auto-upgrades | Config generated by autoupdate enable that enables unattended upgrades. |
| /etc/apt/apt.conf.d/50unattended-upgrades | Rules for unattended-upgrades (what gets updated, reboot window, exclusion list). |
Example os.yml:
unattended:
enabled: true
security_only: true
automatic_reboot: false
automatic_reboot_time: "03:00"
blacklist: []
update:
default_security_only: false
locale:
lang: es_ES.UTF-8
generate: [es_ES.UTF-8, en_US.UTF-8]
timezone: Europe/Madrid
hostname: ""
ntp:
enabled: trueEmpty fields ("") mean "don't touch": the module leaves that setting exactly as it is. That's why hostname comes empty — the instance usually manages it through cloud-init.
Exit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
reboot-required uses the exit code as its answer: 0 means "yes, a reboot is needed" and 1 means "no". That way you can chain it directly in a script without parsing text.
Follow the log live while you debug:
$ sudo tail -f /var/log/imaxe/os.logTroubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| USAGE appears (code 2) | A required argument is missing (locale, zone or hostname) or the format is invalid. | Review the arguments table: the hostname only allows a-z0-9 and hyphens (≤63). |
| The hostname changes back after rebooting | cloud-init rewrites the hostname on every boot. | Disable hostname management in cloud-init, or leave the field in os.yml empty and don't set it by hand. |
locale set is slow or fails | The locales package isn't present and has to be installed/generated. | Retry with the system up to date (imaxe os update); the module installs locales and generates the locale on its own. |
| The time is still off | NTP synchronization is disabled. | Enable it with sudo imaxe os timesync enable and verify with imaxe os timesync status. |
| Unattended upgrades aren't applied | Unattended upgrades were never enabled on this machine. | Run sudo imaxe os autoupdate enable and confirm with imaxe os autoupdate status. |
Stuck with the System module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.