FreeIPA server container
Building FreeIPA server image
This repository contains Dockerfiles and associated assets for building FreeIPA server container images from the official yum/dnf repositories.
There are multiple Dockerfile
s available for images based on various
operating systems. Use -f
option to podman build
or docker build
to pick a specific operating system. For example, running
podman build -t freeipa-server -f Dockerfile.centos-8-stream .
will build image based on CentOS 8 Stream packages using podman, and with
docker build -t freeipa-server -f Dockerfile.fedora-rawhide .
FreeIPA image based on Fedora rawhide will be built with docker. Note that when using docker / moby-engine, the docker daemon needs to be running.
Running FreeIPA server container
The FreeIPA container runs systemd to manage all the necessary services within a single container. Running a systemd-based container may require special handling or parameters to be passed to the container runtime.
With podman, normal podman run
is typically enough.
With docker on systems with cgroups v2, it may be necessary to use user namespace remapping for the container cgroup to be properly created and mounted within the container read-write as systemd expects it, with
{ "userns-remap": "default" }
in /etc/docker/daemon.json
. Restart of the docker service is needed
after this edit. This approach also isolates the root in the container
from the root on the host, which is a good thing in general.
With docker on systems with cgroups v1, it may be necessary to
invoke docker run
with option -v /sys/fs/cgroup:/sys/fs/cgroup:ro
.
On SELinux enabled systems, it may be also necessary to enable running
systemd in containers by setting SELinux boolean container_manage_cgroup
on the host with
setsebool -P container_manage_cgroup 1
The FreeIPA container will store all its configurations and data on
volume mounted to /data
directory in the container. If we create
directory which will hold the server data on the host with
mkdir /var/lib/ipa-data
we can then create the FreeIPA container with podman using
podman run --name freeipa-server-container -ti \
-h ipa.example.test --read-only \
-v /var/lib/ipa-data:/data:Z freeipa-server [ opts ]
and with docker using
docker run --name freeipa-server-container -ti \
-h ipa.example.test --read-only \
-v /var/lib/ipa-data:/data:Z freeipa-server [ opts ]
In case cgroup v1 is used on the host, -v /sys/fs/cgroup:/sys/fs/cgroup:ro
option may be necessary in the docker run
case.
If you receive error like
IPv6 stack is enabled in the kernel but there is no interface that
has ::1 address assigned. Add ::1 address resolution to 'lo' interface.
You might need to enable IPv6 on the interface 'lo' in sysctl.conf.
you might also need to add option
--sysctl net.ipv6.conf.all.disable_ipv6=0
When running DNS server (the --setup-dns
argument to
ipa-server-install
) in a container with read-only root filesystem
(the --read-only
option to podman run
or docker run
), the setup
code in the container won't be able to edit /etc/resolv.conf
in the
container to point it to itself. Add --dns=127.0.0.1
option to the
podman run
or docker run
invocation to allow the FreeIPA server
to reach its own DNS server.
To allow for unprivileged container operation, use the -h ...
option to set the hostname for the FreeIPA server in the container.
If it's not possible to set the hostname for the container, specify it
with IPA_SERVER_HOSTNAME
environment variable, for example with
podman run -e IPA_SERVER_HOSTNAME=...
. This might however not work
with read-only containers.
Do not use the ipa-server-install --hostname ...
argument.
Upon the first invocation with empty directory mounted to /data
,
the container will run either ipa-server-install
or ipa-replica-install
to configure FreeIPA master or replica. For example
podman run -ti -h ipa.example.test --read-only \
-v /var/lib/ipa-data:/data:Z \
freeipa-server ipa-server-install -r EXAMPLE.TEST --no-ntp
will run interactive ipa-server-install
and configure the FreeIPA master
using the inputs provided. For unattended initial installation, use
the -U
argument to ipa-server-install
and specify all the necessary
inputs as argument on the command line, for example
docker run -ti -h ipa.example.test --read-only \
-v /var/lib/ipa-data:/data:Z \
-e PASSWORD=Secret123 \
freeipa-server ipa-server-install -U -r EXAMPLE.TEST --no-ntp
The ipa-server-install
command is the default and can be omitted.
Sometimes it is not convenient or possible to specify the arguments
to ipa-server-install
as arguments to podman run
or docker run
.
In the case they can be specified either using environment variable
IPA_SERVER_INSTALL_OPTS
using the -e
option, or they can be passed
in using file ipa-server-install-options
in the directory mounted
to the container as /data
. For example, when
/var/lib/ipa-data/ipa-server-install-options
contains
--realm=EXAMPLE.TEST
--ds-password=The-directory-server-password
--admin-password=The-admin-password
and podman run
or docker run
is executed with
-v /var/lib/ipa-data:/data:Z
, the content of
ipa-server-install-options
will be passed as arguments to
ipa-server-install
.
Since the ipa-server-install-options
typically contains passwords,
it is also possible to use podman secret create
to store the whole
content of that file, and the invoke podman run
with options like
--secret source=options-with-credentials,target=/data/ipa-server-install-options
to expose the options in the container. The same holds for docker
invocation.
If you want to instruct the container to create a replica, specify the
ipa-replica-install
command in the podman run
or docker run
parameters:
podman run -ti -h ipa.example.test --read-only \
-v /var/lib/ipa-data:/data:Z \
freeipa-server ipa-replica-install [ opts ]
Using ipa-replica-install-options
also works and will invoke
ipa-replica-install
and pass it its content as argument, the same
way ipa-server-install-options
works for ipa-server-install
.
Upon subsequent invocations when /data
is found already populated
with FreeIPA server configuration and data, the options are ignored
and just the necessary services started in the container.
If you want to use the FreeIPA server not just from the host
where it is running but from external machines as well, you
might want to use the -p
options to make the services accessible
externally.
docker run -p 53:53/udp -p 53:53 \
-p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 \
-p 88:88/udp -p 464:464/udp -p 123:123/udp ...
You will then likely want to also specify the --ip-address
option to ipa-server-install
with the IP address of the host,
and also use the --add-host
option to the docker run
/ podman run
with the same IP address, especially when running the container
as read only.
Alternatively, the IPA_SERVER_IP
environment variable via the
-e
option to docker run
/ podman run
can be used to
define what IP address should the FreeIPA server put to DNS as its
address. Using this mechanism will however not update the ipa-ca
record.
If you have existing container with data volume, it should be safe
to shut it down and run new one based on newer image, with the same
data directory bind-mounted to /data
. The container logic will detect
that it is running with data produced by different image and attempt
to upgrade the configuration and data. Of course, keeping backup
of the data directory for cases when the upgrade process fails
is recommended.
IPA-enrolled client in Docker
There are multiple *-client
branches named after OS they are
based on. Check out the branch you prefer and in the root of the
repository, run:
docker build -t freeipa-client .
To run the client container, run it with correctly set DNS and hostname in the IPA domain, or you can link it to the freeipa-server container directly:
docker run --privileged --link freeipa-server-container:ipa \
-e PASSWORD=Secret123 -ti freeipa-client
The first time this container runs, it invokes ipa-client-install
with the given admin password.
Debugging
The container scripts provide some options for debugging:
-
Enable shell script tracing in both the top-level
init-data
script and theipa-server-configure-first
script by setting the$DEBUG_TRACE
environment variable. -
Disable container exit after script failure by setting the
$DEBUG_NO_EXIT
environment variable. After failure, the container will continue running, and can be entered for debugging with e.g.podman exec -it freeipa-server-container bash
. This can also be achieved by specifyingno-exit
as the first word in the [opts] to the container. -
Force container exit after successfully configuring the FreeIPA server by specifying
exit-on-finished
as the first word in the [opts] to the container.
Example usage:
podman run [...] -e DEBUG_TRACE=1 -e DEBUG_NO_EXIT=1 freeipa-server
or
docker run [...] freeipa-server exit-on-finished -U -r EXAMPLE.TEST
You can also try to run
tests/run-partial-tests.sh Dockerfile
or
docker=podman tests/run-partial-tests.sh Dockerfile
which can uncover the general issues with running systemd in containers.
CI in GitHub Actions
To check the general health of the project, see https://github.com/freeipa/freeipa-container/actions where tests are run for various OS versions in the containers.
License
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.