diff options
Diffstat (limited to '')
| -rw-r--r-- | scripts/docker/README.md | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/scripts/docker/README.md b/scripts/docker/README.md new file mode 100644 index 0000000..f6e9ae6 --- /dev/null +++ b/scripts/docker/README.md @@ -0,0 +1,200 @@ +# What is FreeRADIUS? + +The FreeRADIUS Server Project is a high performance and highly +configurable multi-protocol policy server, supporting RADIUS, DHCPv4 +and VMPS. Using RADIUS allows authentication and authorization for a network +to be centralized, and minimizes the number of changes that have to +be done when adding or deleting new users to a network. + +FreeRADIUS can authenticate users on systems such as 802.1x +(WiFi), dialup, PPPoE, VPN's, VoIP, and many others. It supports +back-end databases such as MySQL, PostgreSQL, Oracle, Microsoft +Active Directory, Redis, OpenLDAP. It is used daily to +authenticate the Internet access for hundreds of millions of +people, in sites ranging from 10 to 10 million+ users. + +> [wikipedia.org/wiki/FreeRADIUS](https://en.wikipedia.org/wiki/FreeRADIUS) + + +# How to use this image + +## Starting the server + +```console +$ docker run --name my-radius -d freeradius/freeradius-server +``` + +The image contains only the default FreeRADIUS configuration which +has no users, and accepts test clients on 127.0.0.1. In order to +use it in production, as a minimum you will need to add clients to +the `clients.conf` file, and users to the "users" file in +`mods-config/files/authorize`. + +**Without building a local image with a configuration, the +container will refuse to answer any queries.** + + +## Defining a local configuration + +Create a local `Dockerfile` based on the required image and +COPY in the server configuration. + +```Dockerfile +FROM freeradius/freeradius-server:latest +COPY raddb/ /etc/raddb/ +``` + +The `raddb` directory could contain, for example: + +``` +clients.conf +mods-config/ +mods-config/files/ +mods-config/files/authorize +``` + +Where `clients.conf` contains a simple client definition + +``` +client dockernet { + ipaddr = 172.17.0.0/16 + secret = testing123 +} +``` + +and the `authorize` "users" file contains a test user: + +``` +bob Cleartext-Password := "test" +``` + +Build the image locally: + +```console +$ docker build -t my-radius-image -f Dockerfile . +``` + + +## Using the local configuration + +It should now be possible to test authentication against the +server from the host machine, using the `radtest` utility supplied +with FreeRADIUS and the credentials defined above. + +Start the local container. Ports will need to be forwarded to the +server, typically 1812/udp and/or 1813/udp, for example: + +```console +docker run --rm -d --name my-radius -p 1812-1813:1812-1813/udp my-radius-image +``` + +Send a test request, you will need the `radtest` utility: + +```console +$ radtest bob test 127.0.0.1 0 testing123 +``` + +which should return an "Access-Accept". + +The image can now be stopped with: + +```console +docker stop my-radius +``` + + +## Running in debug mode + +FreeRADIUS should always be tested in debug mode, using option +`-X`. Coloured debug output also requres `-t` be passed to docker. + +```console +$ docker run --rm --name my-radius -t -p 1812-1813:1812-1813/udp freeradius/freeradius-server -X +``` + +Guidelines for how to read and interpret the debug output are on the +[FreeRADIUS Wiki](https://wiki.freeradius.org/radiusd-X). + + +## Security notes + +The configuration in the docker image comes with self-signed +certificates for convenience. These should not be used in a +production environment, but replaced with new certificates. See +the file `raddb/certs/README.md` for more information. + + +## Debugging + +By default if you try to use `gdb` in a Docker container, the +pattach call will fail, and you will not be able to trace +processes. + +In order to allow tracing, the ``--privileged`` flag must be +passed to ``docker run``, this restores any Linux ``cap`` +privileges that would not ordinarily be given. + + +# Image variants + +## `freeradius/freeradius-server:<version>` + +The de-facto image which should be used unless you know you need +another image. It is based on +[Ubuntu Linux](https://hub.docker.com/_/ubuntu/) Docker images. + + +## `freeradius/freeradius-server:<version>-alpine` + +Image based on the [Alpine Linux](https://hub.docker.com/_/alpine/) +Docker images, which are much smaller than most Linux +distributions. To keep the basic size as small as possible, **this +image does not include libraries for all modules that have been +built** (especially the languages such as Perl or Python). Therefore +these extra libraries will need to be installed with `apk add` in +your own Dockerfile if you intend on using modules that require +them. + + +# Building Docker images + +The FreeRADIUS source contains Dockerfiles for several Linux +distributions. They are in +[`freeradius-server/scripts/docker/<os_name>`](https://github.com/FreeRADIUS/freeradius-server/tree/v3.2.x/scripts/docker). + +Build an image with + +```bash +$ cd scripts/docker/<os_name> +$ docker build . -t freeradius-<os_name> +``` + +This will download the OS base image, install/build any dependencies +as necessary, perform a shallow clone of the FreeRADIUS source and +build the server. + +Once built, running ``docker images`` should show the image. + +```bash +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +freeradius-ubuntu16 latest 289b3c7aca94 4 minutes ago 218MB +freeradius-alpine latest d7fb3041bea2 2 hours ago 88.6MB +``` + + +## Build args + +Two ARGs are defined in the Dockerfiles that specify the source +repository and git tag that the release will be built from. These +are + +- source: the git repository URL +- release: the git commit/tag + +To build the image from a specific repository and git tag, set one +or both of these args: + +```console +$ docker build . --build-arg=release=v3.2.x --build-arg=source=https://github.com/FreeRADIUS/freeradius-server.git -t freeradius-<os_name> +``` |