summaryrefslogtreecommitdiffstats
path: root/scripts/docker/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--scripts/docker/README.md200
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>
+```