etc-update Command: Tutorial & Examples

Manage and safely merge configuration file updates on Gentoo Linux systems.

The etc-update command is a specialized utility primarily used on Gentoo Linux to manage updates to configuration files in the /etc directory. When software packages are upgraded or installed, new versions of configuration files often come along and need to be merged with existing customized settings. Instead of blindly overwriting these files, which risks losing important customizations, etc-update provides a controlled, interactive, or automatic approach to merging and updating configuration files. This article explains how etc-update works, its usage, common parameters, practical examples, potential pitfalls, and best practices for maintaining a stable and secure system.

How It Works

The etc-update command scans the /etc directory for configuration files that have updates pending. When a package installs or upgrades a configuration file, the new version is placed alongside the existing one with a special filename pattern starting with ._cfg (for example, /etc/._cfg0000_sshd_config). This allows the system to keep both the old and new versions.

Upon running etc-update, the tool compares each original configuration file with its new counterpart and presents the user with options to:

Replace the existing file with the new version.
Keep the existing file, discarding the new changes.
Interactively merge the two files, reviewing differences and selectively incorporating changes.

The merging is done using a text-based interface powered by the merge tool, which can resolve simple differences automatically or prompt the user for manual conflict resolution. This prevents accidental overwrites of critical custom settings.

By preserving backups of old files and using a reliable merge mechanism, etc-update helps maintain system stability while keeping configuration files up to date.

What It Is Used For

etc-update is used mainly for:

Managing configuration file updates during package upgrades or system maintenance.
Preserving custom modifications in configuration files while integrating new default options.
Preventing service downtime caused by accidental overwrites of configuration files.
Handling configuration files for a variety of services such as SSH (/etc/ssh/sshd_config), filesystem mounts (/etc/fstab), networking, system daemons, and more.
Ensuring consistency and control over configuration file changes in a multi-administrator environment.

Typical configuration files managed by etc-update include:

/etc/ssh/sshd_config
/etc/fstab
/etc/hosts
/etc/profile
/etc/rc.conf (on some systems)
Various service-specific config files installed by packages

Why It Was Invented

Before utilities like etc-update, configuration files were often overwritten automatically during package upgrades, leading to the loss of valuable customizations. System administrators had to manually track changes and merge updates, which was error-prone and time-consuming.

etc-update was created as a safer alternative to automate and standardize the merging process, minimizing human error while preserving important settings. It was specifically designed to work with the Gentoo Linux package management philosophy, where configuration files are frequently updated and customized.

By providing an interactive, controlled update mechanism, etc-update reduces configuration-related issues such as:

Service failures due to incorrect settings.
Security vulnerabilities caused by outdated config options.
Downtime from configuration conflicts or misconfigurations.

How to Use It And Common Command Line Parameters

To run etc-update, open a shell and enter:

etc-update

This will scan for configuration file updates and present a menu-driven interface.

Common Parameters

--automode
Automatically merge files where possible without user interaction. Use cautiously, as it may overwrite custom settings without prompt.
--help
Display help and usage information.
--verbose
Show detailed information about the files being processed.
--version
Show the version information of etc-update.

Interactive Usage

When run without parameters, etc-update displays a numbered list of files with available updates and prompts the user to select one to process. For each file, you can:

View differences between the old and new files.
Choose to merge interactively using the merge tool.
Replace or keep the existing file.

You can quit anytime by entering q.

Practical Examples Using etc-update

Basic Usage

etc-update

Example output:

Scanning Configuration files...
The following is the list of files which need updating, each configuration file is followed by a list of possible replacement files.
1) /etc/ssh/sshd_config
      /etc/._cfg0000_sshd_config
2) /etc/fstab
      /etc/._cfg0000_fstab

Please select a file to edit by entering the corresponding number.
(don't use -3 or -5 if you're unsure what to do)

Select a file number to begin the interactive merge or replacement process.

Automatic Mode
```
etc-update --automode
```
Attempts to merge all configuration files automatically without user interaction. This is convenient for scripted updates but may overwrite custom changes if conflicts are complex.
Merging a Single File

After selecting a file from the list, etc-update invokes the merge tool. You will see conflict markers in the text interface, such as:
```
   <<<<<<< /etc/ssh/sshd_config
   # Existing custom setting
   =======
   # New default setting
   >>>>>>> /etc/._cfg0000_sshd_config
```
You can manually edit the merge buffer to choose which lines to keep.

Typical Output Explained

The initial output lists all configuration files with pending updates, showing the original file and the corresponding new version with a ._cfg prefix.

After selecting a file, you see a three-way merge interface or a prompt to choose an action. The tool may print messages indicating success or conflict status.

If there are no files to update, etc-update will print a message like:

No configuration files need updating.

Potential Problems and Pitfalls

Common Problems

Overwriting Custom Settings
Automatic merging or careless replacement may discard important customizations, causing service failures or network issues.
Merge Conflicts
Complex configuration changes may lead to merge conflicts that require manual resolution.
Neglecting Updates
Ignoring configuration file updates can leave the system vulnerable to security issues or misconfiguration.

Troubleshooting Tips

Always review merges carefully, especially when using --automode.
If a merge conflict occurs, edit the file manually to resolve conflicts using <<<<<<<, =======, and >>>>>>> markers.
Use version control (e.g., git) on /etc to track changes over time.
Backup critical configuration files before running updates.
If etc-update reports errors, check file permissions and ownership in /etc.

Example Problems Solved

Updating SSH configuration to include new recommended options without losing custom tweaks.
Incorporating additions to /etc/fstab safely during kernel or filesystem upgrades.
Merging changes in service daemon configs after package updates.

Tips And Best Practices

Always run etc-update after package upgrades that affect configuration files.
Prefer interactive mode to review each change.
Use --automode only in trusted, automated environments.
Backup /etc regularly or use version control for auditability.
Familiarize yourself with the syntax of configuration files you manage.
Document any manual merges or customizations for future reference.

Comparison With Alternatives

Gentoo also provides the dispatch-conf command which offers similar functionality with some differences:

dispatch-conf supports a different merging backend and supports a more graphical interface.
etc-update is simpler and more straightforward for basic merging.
Both tools can be used; choice depends on administrator preference.

Manual editing or scripting merges is possible but error-prone compared to using these specialized tools.

Security Considerations

Ensure only privileged users (usually root) can run etc-update and modify /etc files.
Improper merges can introduce misconfigurations leading to security vulnerabilities.
Verify file permissions and ownership after updates.
Be cautious with automated merges on production systems.

Scripting And Automation

While etc-update is primarily interactive, the --automode parameter allows integration into scripts or automated system maintenance workflows. Combine with package managers or cron jobs carefully.