{"id":19678674,"url":"https://github.com/tillt/docker-kdc","last_synced_at":"2025-04-29T04:30:42.352Z","repository":{"id":23720907,"uuid":"27093821","full_name":"tillt/docker-kdc","owner":"tillt","description":"Docker container generator for a Kerberos KDC.","archived":false,"fork":false,"pushed_at":"2020-08-16T22:35:46.000Z","size":31,"stargazers_count":51,"open_issues_count":4,"forks_count":21,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-05T13:01:32.265Z","etag":null,"topics":["docker","kdc","kerberos"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tillt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-24T20:30:39.000Z","updated_at":"2025-03-21T18:31:17.000Z","dependencies_parsed_at":"2022-08-22T03:30:54.347Z","dependency_job_id":null,"html_url":"https://github.com/tillt/docker-kdc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillt%2Fdocker-kdc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillt%2Fdocker-kdc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillt%2Fdocker-kdc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillt%2Fdocker-kdc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tillt","download_url":"https://codeload.github.com/tillt/docker-kdc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251432619,"owners_count":21588616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","kdc","kerberos"],"created_at":"2024-11-11T17:39:10.355Z","updated_at":"2025-04-29T04:30:42.060Z","avatar_url":"https://github.com/tillt.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"docker-kdc\n==========\n\nDocker container generator for a Heimdal Kerberos 5 KDC.\n\nThe intension here is to ease the first steps with Kerberos while also allowing a customized, automated setup for development or test integration. Usable on plain Linux as well as on OSX.\n\n---\n\n# Dependencies\n- Docker\n- jq 1.4\n\n#### Linux specific dependency\n- Heimdal Kerberos 5\n\n#### OSX specific dependency\n- boot2docker\n\n---\n\n# Usage\n\n### Check your configuration\nThe default configuration is likely to be fine for your first steps, validate it using the `config` command.\n```\n./kdc config\n```\n\nYou will receive a list of relevant configuration information. The defaults are derived from your hosts' configuration to allow for a quick test setup.\n\n**Example output: `./kdc config`**\n```\nSystem\n  fqdn:      hostname.domain.name\nKDC\n  nat:       127.0.0.1\n  port:      48088\nKerberos\n  domain:    domain.name\n  realm:     DOMAIN.NAME\n  principal: tillt/hostname.domain.name@DOMAIN.NAME, password: matilda\n```\n\n\n### Build the docker image\n```\n./kdc build\n```\n\nThis will render the image which is based on plain ubuntu 14.04. Additionally the packages `heimdal-kdc` as well as `libsasl2-modules-gssapi-heimdal` are installed. The latter is useful only if you extend this container image by further applications making use of Kerberos authentication via SASL2's GSSAPI.\n\n\n### Run the container\n```\n./kdc start\n```\n\nOn OSX, this step starts by setting up the VM (via boot2docker). Then, on all host systems, the container is started in detached mode, allowing you to keep on working with this shell without having to fork another process. The container name is directly derived from the hostname supplied via the configuration (see [Configuration](#configuration)).\n\n### Watch the KDC server log file\n```\ndocker exec -it kdc tail -f /var/log/heimdal-kdc.log\n```\n\n### Run a quick test\n```\n./kdc test\n```\nOn OSX, this first checks if the VM is active. Then, on all hosts systems, a network connection to the KDC is attempted.\n\n### Prepare the environment\n```\n$(./kdc shellinit)\n```\n\nA Kerberos client needs access to a configuration file. To prevent having to edit the system wide configuration file (`/etc/krb5.conf`) a local, minimal version is rendered and supplied once the container has gotten started. Additionally, the keytab also gets exported and hence needs to be accessible for clients making use of password-less authentication. To make use of the files, environment variables that are interpreted by Kerberos clients are prepared.\n\n### Render a ticket supplying the principal password\n```\nkinit tillt/hostname.example.com@EXAMPLE.COM\n```\n\nPassword: `matilda`\n\n#### Check the ticket\n```\nklist\n```\n\nOn OSX you could also use the Ticket Viewer to check the details of the issued ticket (`open \"/System/Library/CoreServices/Ticket Viewer.app\"`).\n\n**Example output: `klist`**\n\n```\nCredentials cache: API:42926CE1-63E2-4C66-B2D7-00B2F198182F\n        Principal: tillt/hostname.example.com@EXAMPLE.COM\n\n  Issued                Expires               Principal\nNov 26 11:06:25 2014  Nov 26 21:06:25 2014  krbtgt/EXAMPLE.COM@EXAMPLE.COM\n```\n\n#### Remove the ticket\n```\nkdestroy\n```\n\n### Check the content of the keytab\n```\nktutil --keytab=krb5.keytab list\n```\n\n**Example output: `ktutil --keytab=krb5.keytab list`**\n```\nkrb5.keytab:\n\nVno  Type                     Principal                              Aliases\n  1  aes256-cts-hmac-sha1-96  tillt/hostname.example.com@EXAMPLE.COM\n  1  des3-cbc-sha1            tillt/hostname.example.com@EXAMPLE.COM\n  1  arcfour-hmac-md5         tillt/hostname.example.com@EXAMPLE.COM\n```\n\n### Render a ticket using keytab based authentication\n```\nkinit -kt krb5.keytab tillt/hostname.example.com@EXAMPLE.COM\n```\n\n### Check the ticket\n```\nklist\n```\n\n[...]\n\n\n### Stop the container\n```\n./kdc stop\n```\n\nThis will stop the KDC server, stop and remove the container and additionally remove the temporary keytab and configuration files.\n\n\n### Customize your configuration\nYou may use environment variables and/or a JSON configuration file for customizing the setup. The default filename for the JSON file is `kdc.json` but may be configured by the environment variable  KDC_CONFIG.\n\nThe default configuration is most likely good enough for your first experiments.\n\n#### Kerberos principal\n| env. variable | config node | default   |\n|---------------|-------------|-----------|\n| KDC_PRINCIPAL | id          | `tillt`   |\n\n**Note**: using a configuration file allows setting up multiple principals (via **principals[ ].id**).\n\n#### Kerberos password\n| env. variable | config node | default   |\n|---------------|-------------|-----------|\n| KDC_PASSWORD  | password    | `matilda` |\n\n**Note**: using a configuration file allows setting up multiple passwords (via **principals[ ].password**).\n\n#### Kerberos client\n| env. variable | config node | default                 |\n|---------------|-------------|-------------------------|\n| KDC_CLIENT    | n/a         | oufput of `hostname -s` |\n\n**Note**: when no principals are defined via configuration file, KDC_CLIENT is used to create a full service principal (schema: KDC_PRINCIPAL **/** KDC_CLIENT **.** KDC_DOMAIN_NAME **@** KDC_REALM_NAME ).\n\n#### KDC hostname\n| env. variable | config node | default   |\n|---------------|-------------|-----------|\n| KDC_HOST_NAME | n/a         | `kdc`     |\n\n#### External KDC IP\n| env. variable | config node | default     |\n|---------------|-------------|-------------|\n| KDC_NATHOST   | nat         | `127.0.0.1` |\n\n**Note**: this value gets overridden by the kdc script on OSX to allow for connecting to the boot2docker VM. You shouldn't really need to override this in any case.\n\n#### External KDC port\n| env. variable | config node | default   |\n|---------------|-------------|-----------|\n| KDC_PORT      | port        | `48088`   |\n\n#### Kerberos domain name\n| env. variable   | config node | default                                  |\n|-----------------|-------------|------------------------------------------|\n| KDC_DOMAIN_NAME | domain      | hostname cut off output of `hostname -f` |\n\n#### Kerberos realm name\n| env. variable  | config node | default                              |\n|----------------|-------------|--------------------------------------|\n| KDC_REALM_NAME | realm       | capitalized value of KDC_DOMAIN_NAME |\n\n**Note**: it is common practice to simply use the domain-name but all capitalized for this.\n\n#### Configuration filename\n| env. variable  | config node | default       |\n|----------------|-------------|---------------|\n| KDC_CONFIG     | n/a         | `kdc.json`    |\n\n**templates/kdc.json**\n```\n{\n  \"principals\": [\n    {\n      \"id\": \"tillt/host.example.com@EXAMPLE.COM\",\n      \"password\": \"herbert\"\n    },\n    {\n      \"id\": \"tillt@EXAMPLE.COM\",\n      \"password\": \"herbert\"\n    }\n  ],\n  \"domain\": \"example.com\",\n  \"realm\": \"EXAMPLE.COM\",\n  \"ip\": \"127.0.0.1\",\n  \"port\": 48088\n}\n```\n\n---\n\n# Reference\n\n```\n./kdc start|stop|build|clean|config|shellinit\n```\n\n## build\nBuilds the docker image.\n\n## start\nStarts the container in detached mode while also producing a Kerberos configuration file (`krb5.conf`) as well as a Kerberos keytab (`krb5.keytab`) locally. \n\nNote that the keytab is only readable/usable by the current user unless you change its access rights which is not recommended for production environments.\n\n## stop\nStops the container and deletes `krb5.conf` as well as `krb5.keytab`.\n\n## clean\nRemoves the docker image.\n\n## config\nShows relevant configuration information.\n\n## test\nChecks if the KDC is reachable and accepting connections.\n\n## shellinit\nRenders the environment variables needed for using the KDC. KRB5_CONFIG points towards the temporary configuration file. KRB5_KTNAME points towards the temporary keytab file.\n\n---\n\n# TODO\n\n- strip down base image to squeeze out some space\n- refactor code into something less convoluted\n- allow for an admin server, not just the KDC\n\n\n---\n\n# Credits\n\nThis script was inspired by some work of a co-worker of mine, Matthias Veit. Matthias did the hard work of finding out how to properly route docker ports on boot2docker hosts.\n\n---\n\n# Author\n\n* [Till Toenshoff](https://github.com/tillt) ([@ttoenshoff](https://twitter.com/ttoenshoff))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftillt%2Fdocker-kdc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftillt%2Fdocker-kdc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftillt%2Fdocker-kdc/lists"}