cepharum/samba-pdc repository overview

⁠INPAS 3rd-gen: Samba AD PDC

⁠License

MIT

⁠About

This project is maintaining a docker container running a Samba4-based PDC for managing an Active Directory (AD) in setups lacking a genuine Windows Server.

⁠Important Note For INPAS Development

This project isn't meant to run as part of 3rd-gen INPAS.

It must not be included with docker-compose.yml file of INPAS installer but has to run on a separate server or in a dedicated VM.

⁠Setup

This guide explains how to run a primary domain controller (PDC) in a virtual machine (VM).

⁠Common Preparations

You need to pick some basic information for setting up the PDC:

1. A fully qualified domain name is required. There are certain constraints to be obeyed.⁠

   Example for this guide: mypdc.samba.mydomain.com

2. A fixed IP address must be assigned to the PDC. It mustn't change over time.

   Example for this guide: 10.1.2.3

3. The IP address of at least one DNS resolver is required.

   Example for this guide: 8.8.8.8*

Whenever either of these examples are used in the following guide you should replace them with actual values of your runtime environment.*

⁠Prepare Virtual Machine

1. Download installation image for the Linux distribution of your choice. This tutorial is using Alpine Linux⁠ for its simplicity and small memory footprint. Pick the x86_64 version in box labelled Virtual (preferred) or Standard.

2. Create a VM using a software like Oracle VirtualBox⁠ or Microsoft Hyper-V⁠. The latter comes included with Pro- and Enterprise-editions of Windows 10.

   • Make sure its suitable for running Linux.
   • Use a network bridge so the VM is exposed to your local LAN.
     • Don't use NAT or internal-only networks for usually having issues in one way or the other.
     • At least make sure assigned IP is fixed.
   • Select the downloaded image for installing operating system in created VM.

3. Start VM and install selected Linux operating system. This applies to installing Alpine Linux:

   • Log in as root.
   • Enter setup-alpine.
   • Answer questions of its installer script.
     • The requested hostname should be first segment of fully qualified domain name picked before. So, in case of mypdc.samba.mydomain.com you need to provide mypdc there.
     • Configure network while obeying requirement, that VM's IP must not change over time.

4. Restart VM after installation.

5. Install docker and docker-compose. Use these steps with Alpine Linux:

   • Log in as root.
   • Run apk update.
   • Run apk add nano.
   • Run nano /etc/apk/repositories.
   • Remove # at beginning of line include community. If there are multiple lines matching pick the one that doesn't include edge but some actual version number like v3.10.
   • Save file and leave editor by pressing Ctrl+X first and Y second.
   • Run apk update again.
   • Run apk add docker docker-compose.
   • Run rc-update add docker.
   • Run service docker start.

6. Create a file named docker-compose.yml in your VM using nano and paste the following content:

   version: "3.6"
   
   services:
     pdc:
       image: cepharum/samba-pdc
       container_name: pdc
       volumes:
        - "/etc/localtime:/etc/localtime:ro"
        - "state:/var/lib/samba"
        - "config:/etc/samba/saved"
       cap_add:
         - SYS_ADMIN
       environment:
         - TERM=rxvt
         - PDC_FQDN
         - PDC_IP
         - PDC_PASSWORD
         - PDC_DNS_FORWARDER
         - PDC_DNS_SEARCH
         - PDC_DEBUG
         - PDC_WEAK_LDAP
         - PDC_WEAK_PASSWORDS
       ports:
         - "53:53"
         - "53:53/udp"
         - "88:88"
         - "88:88/udp"
         - "135:135"
         - "137:137/udp"
         - "138:138/udp"
         - "139:139"
         - "389:389"
         - "389:389/udp"
         - "445:445"
         - "464:464"
         - "464:464/udp"
         - "636:636"
         - "3268:3268"
         - "3269:3269"
       restart: always
   
   volumes:
     state:
     config:
   

   Copy

7. Create file .env containing the following variables:

   • PDC_FQDN is assigned the fully qualified domain name picked before.
   • PDC_HOST_IP is assigned the IP of VM.
   • PDC_DNS_FORWARDER is assigned the IP of DNS resolver to use for all queries PDC isn't authoritative for.

   Example:

   PDC_FQDN=mypdc.samba.mydomain.com
   PDC_IP=10.1.2.3
   PDC_DNS_FORWARDER=8.8.8.8
   

   Copy

8. Start the PDC.

   On first run the PDC will create its domain. You have to provide a password for the domain's administrator user. Don't put it into the .env file but use this command:

   read -esp "password: " && echo && PDC_PASSWORD="$REPLY" docker-compose up -d
   

   Copy

   This will ask for password and start the PDC.

   In case this command is rejected due to not supporting option -e it is okay to omit that option:

   read -sp "password: " && echo && PDC_PASSWORD="$REPLY" docker-compose up -d
   

   Copy

   However, this command might reveal entered password if you intentionally or accidentally cancel input instead of confirming it by pressing Ctrl+C instead of Enter.

   When running docker-compose via sudo you need a slightly different command:

   read -esp "password: " && echo && sudo -E PDC_PASSWORD="$REPLY" docker-compose up
   

   Copy

   Check output of starting PDC for any errors:

   docker-compose log
   

   Copy

   At any time you can stop the PDC:

   docker-compose down
   

   Copy

   When you want to restart PDC use this simplified command:

   docker-compose up -d
   

   Copy

   If you want to start fresh - e.g. after failed initialization of PDC or after changing parameter in .env - you can use this command to shut down the PDC and drop any volume attached for persisting data:

   docker-compose down -v
   

   Copy

   On next restart you need to use the command provided above asking for password before initializing and starting the PDC.

9. Assure the VM and all clients are using the PDC for DNS resolving.

   On behalf of the VM you need to adjust the file /etc/resolv.conf to look like this:

   nameserver 10.1.2.3
   search samba.mydomain.com
   

   Copy

   Usually, the file /etc/resolv.conf is replaced on every start of the VM at least. Make sure to disable this feature. In Alpine Linux you need to edit or create a file /etc/udhcpc/udhcpc.conf appending following content:

   RESOLV_CONF=no
   

   Copy

⁠Providing Custom Certificate

It is possible to provide a custom certificate to use instead of the auto-generated self-signed cert. It is read from the volume also used to persist the configuration.

1. Set up the PDC as described above. Make sure to have it started at least once so the volume is created.

2. While it's running use this command to enter the container for pasting stuff into the volume:

   docker-compose exec pdc bash
   

   Copy

3. When in container changed to folder /etc/samba/saved and use nano to create these files:

   • /etc/samba/saved/cert.pem
   • /etc/samba/saved/key.pem

   In addition you may provide the CA's chaining certificates in file

   • /etc/samba/saved/ca.pem

4. Leave the container, shut down the PDC container (without option -v) and restart again.

⁠Troubleshooting

⁠LDAP: can't connect to server

By default the Samba PDC is providing LDAP access requiring sufficiently stronger security.

• All queries have to be bound (which is they must be authenticated).
• When connecting unencryptedly SASL binds must be used.
• When connected encryptedly simple binds are possible as well.

However, by default the PDC is running with an auto-generated self-signed cert which isn't causing basically encrypted connections to be considered secure enough to count. Thus you are stuck to use a SASL binding. But SASL doesn't like the self-signed cert either, so you can't use LDAP without applying one of two options:

1. Install certificate properly signed by some certificate authority.
2. Weaken LDAP security by setting related parameter in your .env file.

See Samba Wiki⁠ for additional information.

⁠Credits

This implementation has been inspired by:

• https://github.com/Fmstrat/samba-domain⁠