Local repository servers

5.6. Local repository servers#

A local repository mirrors packages from Univention update servers to your infrastructure. This gives you control over updates, reduces bandwidth usage, and enables offline operations in your environment.

Use a local repository when you manage multiple systems, especially across distributed locations or with limited internet connectivity. For single-system installations with reliable internet access, you can use online repositories directly.

After you set up a local repository, you install and manage packages from it. For package installation methods, see Package installation and management.

This section covers creating, configuring, and maintaining local repositories.

Benefits of using a local repository

  • Reduced bandwidth usage: Download updates once from Univention servers, then distribute to all systems locally, significantly reducing internet bandwidth consumption in environments with many systems.

  • Offline updates: Update systems without requiring internet access. This is useful for air-gapped networks or locations with unreliable connectivity.

  • Faster deployments: Local package distribution is faster than downloading from remote servers, especially in geographically distributed environments or over slow network links.

  • Update control: Maintain a local copy of packages, giving you control over which versions are available and when systems can access them.

Considerations for maintaining a local repository

  • Synchronization effort: You must regularly synchronize the local repository with upstream Univention servers to stay up to date with security and stability updates.

  • Administrative overhead: You must monitor repository health and manage synchronization.

Choosing whether to use a local repository

Use a local repository server when you manage multiple Nubus for UCS systems, particularly across distributed locations or with limited internet connectivity. For single-system installations or environments with reliable, high-bandwidth internet access, use online repositories directly.

Nubus for UCS automatically generates APT package sources in the /etc/apt/sources.list.d/ directory based on settings for release, errata updates, and add-on components. If you need additional repositories on a system, you can enter them in the /etc/apt/sources.list file.

By default, new installations use the Univention repository at https://updates.software-univention.de.

Repository package status

Univention classifies packages in its repository as either maintained or unmaintained. All packages in the standard package scope are in maintained status. Univention provides security updates in a timely manner only for maintained packages. You can view the list of maintained packages on a Nubus for UCS system at /usr/share/univention-errata-level/maintained-packages.txt.

Univention doesn’t provide security updates or other maintenance for unmaintained packages. To verify whether your system has unmaintained packages installed, run the univention-list-installed-unmaintained-packages command.

Repository components

To manage which repository components your system uses, configure the UCR variable repository/online/component/COMPONENTNAME, where COMPONENTNAME is the name of the component. Set the variable to no to exclude a component from synchronization, or leave it unset to use the default behavior.

5.6.1. Create and update a local repository#

This section describes how to create and maintain a synchronized local repository with upstream Univention servers.

Prerequisites

To create a local repository, you need Root user credentials to run the repository commands in a terminal.

Optional: Estimate required disk space
Explanation and commands

Before you initialize the repository, you can estimate how much disk space you need. The required space depends on which Nubus for UCS versions you mirror.

Run the command in Listing 5.6 on your Nubus for UCS system to calculate the estimated size. The command reads the current Nubus for UCS version from UCR variables, retrieves the list of available patch level releases from the upstream release metadata, and sums the package sizes from each suite’s index.

Listing 5.6 Estimate total repository size#
$ eval "$(ucr shell version/version version/patchlevel)"
$ cat << EOT > /tmp/get_suites.py
import json, sys
major, minor = map(int, '${version_version}'.split('.'))
r = json.load(sys.stdin)
for m in r['releases']:
  for n in m['minors']:
    for p in n['patchlevels']:
      if m['major'] == major and n['minor'] == minor:
        v = f'{m["major"]}{n["minor"]}{p["patchlevel"]}'
        print(f'ucs{v} errata{v}', end=' ')
EOT
$ SUITES=$(curl -sf \
    https://updates.software-univention.de/ucs-releases.json \
    | python3 /tmp/get_suites.py)
$ BASE=https://updates.software-univention.de/dists
$ for suite in $SUITES; do \
    curl -sf "$BASE/$suite/main/binary-amd64/Packages.xz"; \
  done | xzcat \
    | awk '/^Size:/{sum+=$2} END{printf "%.1f GB\n", sum/1073741824}'
$ rm /tmp/get_suites.py

Note

The result is an upper bound. apt-mirror stores packages in a shared pool, so packages that appear in multiple suites are only stored once on disk. The actual disk usage is therefore somewhat lower than the estimate.

The estimate doesn’t include source packages. If you set repository/mirror/sources to yes, add additional space for those.

Important

During synchronization, apt-mirror requires temporary working space in addition to the final repository size. Ensure at least twice the estimated size in free disk space before you start.

Initialize the repository

The univention-repository-create command initializes a local repository and begins synchronization with upstream Univention servers. The command installs the univention-debmirror package, if the system doesn’t already have it. Synchronization time depends on your connection bandwidth and the repository size. The command also enables the local repository by setting the UCR variable local/repository to yes.

To initialize the repository, run the command from Listing 5.7 in a terminal. The command requires your confirmation to proceed. After confirmation, synchronization begins automatically. It stores the repository in the /var/lib/univention-repository/mirror/ directory by default.

When initialization completes, the command shows instructions for configuring other systems. Follow these instructions to configure them to use this repository.

Listing 5.7 Create a local repository#
$ univention-repository-create

Tip

Monitor synchronization progress in the repository log file: /var/log/univention/repository.log

Synchronize the repository regularly

After the initial repository creation, use the univention-repository-update command to keep the repository synchronized with upstream Univention servers, as shown in Listing 5.8. Subsequent synchronization runs download only changed packages, so they’re faster than the initial creation.

Listing 5.8 Update a local repository#
$ univention-repository-update net
Synchronize repositories across locations

You can also synchronize local repositories across multiple locations. For example, maintain a main repository at company headquarters and synchronize it to local repositories at individual locations.

Use a main repository for multiple locations

When you manage Nubus for UCS systems across multiple locations, you can use a centralized main repository instead of having each location maintain its own repository.

In this scenario, set up one main repository at your organization headquarters that synchronizes with upstream Univention servers. At each remote location, configure the systems to use the main repository as their repository server instead of synchronizing directly from upstream.

Configure remote locations to use the main repository by setting the UCR variable repository/mirror/server to the FQDN of the main repository on those systems. The systems still run univention-repository-update net to synchronize locally, but they pull packages from your main repository instead of from upstream.

Error handling

If the commands fail, check the following error codes:

Exit code 0:

Command completed successfully.

Exit code 1:

A configuration error occurred, or the user aborted the operation.

Exit code 5:

Another updater process is already running; wait for completion and retry.

For detailed error messages, validate the repository log file: /var/log/univention/repository.log

5.6.2. Configure the repository server#

After you create a local repository, you need to configure your systems to use it. This section shows you three ways to do this: through the management module for individual systems, through the Univention Configuration Registry for command-line configuration, and through LDAP policies when you manage multiple systems centrally.

The default value for the repository server URL is https://updates.software-univention.de.

Configuration through management module

In the Repository Settings management module, specify the Repository server URL. Find the module at Software ‣ Repository Settings. Use this approach for individual system configuration through the graphical interface.

Configuration through Univention Configuration Registry

You can specify the repository server URL in the UCR variable repository/online/server. Use this approach for individual system configuration from the command line.

Policy-based configuration of the repository server

You can also specify the repository server using the Repository server policy in the Computers module. The selection field shows only Nubus for UCS server systems with a configured DNS entry. Use this approach to configure multiple systems centrally in larger environments.

All configuration methods—the management module, Univention Configuration Registry, and policy-based configuration—modify the same system files:

  • /etc/apt/sources.list.d/15_ucs-online-version.list

  • /etc/apt/sources.list.d/20_ucs-online-component.list

To verify that your configuration is correct, validate that the repository server URL in these files matches the value in the UCR variable repository/online/server. The 20_ucs-online-component.list file only contains repository entries when you configure components.

Listing 5.9 shows how the repository server URL appears in the file.

Listing 5.9 Repository server URL in sources.list.d file (excerpt)#
deb https://updates.software-univention.de/ ucs520 main

5.6.3. Maintain the local repository#

Regular maintenance ensures optimal performance and manages disk space efficiently.

Schedule synchronization

Run repository synchronization weekly on Wednesday evening or Thursday morning to stay current with weekly upstream package updates.

Configure the synchronization task using the univention-repository-update net command through either Univention Configuration Registry or an LDAP-based scheduling policy. Listing 5.10 shows an example using UCR variables. The time format is hour minute day month weekday. This example synchronizes the repository every Wednesday at 22:00 in your local time zone. Adjust the schedule based on your organizational needs and network traffic patterns.

Listing 5.10 Configure weekly repository synchronization via UCR#
$ univention-config-registry set \
   cron/repository-sync/command='/usr/sbin/univention-repository-update net' \
   cron/repository-sync/time='22 * * * 3'
Monitor repository health

After each synchronization, verify that it completed successfully.

Check the exit code of the synchronization command— exit code 0 indicates success. Review the repository log file for error messages or warnings. If errors occur, consult the Troubleshooting repository problems section for diagnosis and resolution.

Review disk usage to ensure sufficient space for future synchronizations.

Manage disk space

Disk usage grows over time as upstream adds package versions. Regular cleanup prevents disk space exhaustion.

  • Limit the version range using the UCR variables repository/mirror/version/start and repository/mirror/version/end. The system synchronizes only versions within this range.

  • Exclude optional components by setting the UCR variable repository/online/component/COMPONENTNAME to no, where COMPONENTNAME is the component name you want to deactivate. The system excludes this component from the next synchronization.

  • Exclude source packages using the UCR variable repository/mirror/sources if you don’t require them, since source packages increase repository size significantly.

  • Prune old kernel packages using the univention-prune-kernels command to remove outdated kernel packages and free disk space.

Review and plan

Review your repository configuration and growth patterns quarterly to anticipate storage needs.

Monitor repository size trends. If growth consistently approaches your disk capacity, consider expanding storage or adjusting your version retention policy.

Verify that your version retention strategy matches your UCS support lifecycle. Univention provides security updates for maintained versions. Remove versions that are no longer in your support scope.

Plan for major UCS releases in advance of their publication. Ensure adequate disk space before the release synchronization begins.

5.6.4. Troubleshooting repository problems#

If you encounter issues when creating or updating a local repository, use the following guidance to diagnose and resolve common problems.

Review the repository log file /var/log/univention/repository.log for detailed error messages and diagnostic information.

Repository creation or update fails to start

The command returns exit code 5 because another updater process is running.

Verify if another univention-repository-create, univention-repository-update, or system update process is active on the system. Wait for the other process to complete, then retry your command.

Configuration fails to apply or appears incorrect

The command completes with exit code 1, or the system isn’t using the configured repository server.

Confirm that you set the following Univention Configuration Registry variables correctly:

After you corrected any configuration, review the files to confirm the changes took effect: /etc/apt/sources.list.d/15_ucs-online-version.list and /etc/apt/sources.list.d/20_ucs-online-component.list.

Mirror server pointing to itself

The command fails with exit code 1 when you configure the mirror server to point to the local system instead of an upstream repository server.

Verify that the UCR variable repository/mirror/server doesn’t contain the FQDN of your local system. It must point to a valid upstream repository server, like https://updates.software-univention.de.

Synchronization is slow or stalls

The initial repository synchronization downloads all packages and can take several hours depending on network bandwidth and repository size.

If synchronization appears to stall, verify network connectivity to the repository server and ensure you have sufficient disk space on your system.

Repository server unreachable

Your system can’t connect to the configured repository server. Verify the following:

  • Network connectivity exists from your system to the repository server.

  • DNS resolution works for the repository server hostname.

  • The repository server URL in the UCR variable repository/online/server is correct.

  • Firewall rules allow access to the repository server.

Insufficient disk space

The system runs out of disk space during synchronization.

Verify that you have sufficient disk space available in the directory you configured in the UCR variable repository/mirror/basepath. The default path is /var/lib/univention-repository/.

The amount of space you need depends on which UCS versions and components you choose to mirror.

Not running with sufficient permissions

The command fails when you don’t run it with root privileges. Run all repository management commands as the root user.

On this page