{"id":27161738,"url":"https://github.com/costela/nss-docker","last_synced_at":"2025-06-22T00:33:02.300Z","repository":{"id":57575025,"uuid":"133563574","full_name":"costela/nss-docker","owner":"costela","description":"Name Service Switch plugin for docker and docker-compose","archived":false,"fork":false,"pushed_at":"2019-01-31T20:45:47.000Z","size":32,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T00:57:42.001Z","etag":null,"topics":["dns","docker","docker-compose","name-service-switch","nss"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/costela.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":"2018-05-15T19:28:16.000Z","updated_at":"2025-02-19T19:08:47.000Z","dependencies_parsed_at":"2022-09-19T12:11:50.475Z","dependency_job_id":null,"html_url":"https://github.com/costela/nss-docker","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/costela/nss-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costela%2Fnss-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costela%2Fnss-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costela%2Fnss-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costela%2Fnss-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/costela","download_url":"https://codeload.github.com/costela/nss-docker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costela%2Fnss-docker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261217237,"owners_count":23126245,"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":["dns","docker","docker-compose","name-service-switch","nss"],"created_at":"2025-04-09T00:57:47.896Z","updated_at":"2025-06-22T00:32:57.276Z","avatar_url":"https://github.com/costela.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/costela/nss-docker.svg?branch=master)](https://travis-ci.org/costela/nss-docker)\n[![Go Report Card](https://goreportcard.com/badge/github.com/costela/nss-docker)](https://goreportcard.com/report/github.com/costela/nss-docker)\n\n**NOTE**: This project is a proof-of-concept. For an easier, more portable solution, try [docker-etchosts](https://github.com/costela/docker-etchosts).\n\n# nss-docker\n\nSimple backend plugin for `libc`'s [name service switch](http://www.gnu.org/software/libc/manual/html_node/Name-Service-Switch.html) to query a local docker for running containers.\n\nThis enables resolving containers' IPs locally based on container name or alias.\n\nAdditionally, `nss-docker` supports `docker-compose` by optionally organizing containers' domain names by project.\n\n## Installation\n\nIn order to compile `nss-docker` you will need the C headers for `libc`. These can be installed in Debian variants\n(including Ubuntu) with the `libc6-dev` package and in Redhat variants with the `glibc-headers` package.\n\n- `go get -d github.com/costela/nss-docker`\n- `cd $(go env GOPATH)/src/github.com/costela/nss-docker`\n- `dep ensure -vendor-only` (you may need to install [dep](https://github.com/golang/dep))\n- `sudo make install`\n- add `docker` to the `hosts` line in `/etc/nsswitch.conf`. The entry should be placed before other network\nbackends like `dns` or `mdns`, to ensure faster resolution.\n\n⚠ *Note*: `nss-docker` requires access to the docker daemon as the user performing the queries (commonly achieved by adding\nthe user in question to the `docker` group). This has security implications, since any user with access to the docker daemon can trivially bypass local permission restrictions.\n\n## Configuration\n\nThe configuration is stored as JSON and searched in this order: `~/.nss_docker.json`, `/etc/nss_docker.json`\n\nThe following configuration keys are currently supported:\n\n* `Suffix`: (default: `.docker`) the TLD which will be appended to all containers. Searches not under this TLD will\nbypass this plugin.  \nThis is useful if you want to test something using OAuth locally, since you can simulate real TLDs (which, of course,\nwill be shadowed by the `nss-docker` domains)\n* `IncludeComposeProject`: (default: `true`) whether to include the `docker-compose` project name in the search. When\ntrue, services will be found with the form `SERVICE.PROJECT.SUFFIX`. Otherwise only `SERVICE.SUFFIX` will be searched,\nwhich simplifies names, but increases collision risk.\n\n## Multiple docker-compose projects\n\nIf your workflow involves multiple docker-compose projects using the same service names (e.g. a generic name like\n\"frontend\"), a simple `SERVICE_NAME.SUFFIX` search will not be enough. In this case, a lookup will always return the\nfirst found container.\n\nTo avoid this problem, `nss-lookup` includes the docker-compose project name in the domain, i.e.: `SERVICE_NAME.PROJECT_NAME.SUFFIX`.\n\nAn alternative to this approach would be to disable project-based search (`IncludeComposeProject: false` in the\nsettings) and use aliases to make those services unique which you wish to make accessible:\n\nIn `projectA/docker-compose.yml`:\n```yaml\nservices:\n  frontend:\n    ...\n    networks:\n      default:\n        aliases:\n          - projectA\n    ...\n```\n\nAnd in `projectB/docker-compose.yml`:\n```yaml\nservices:\n  frontend:\n    ...\n    networks:\n      default:\n        aliases:\n          - projectB\n    ...\n```\n\n## Limitations\n\n### Linux-only\n\nSince this project builds on libc's [name service switch](http://www.gnu.org/software/libc/manual/html_node/Name-Service-Switch.html), it is only compatible with Linux.\n\n### Cross-container name resolution\n\nThe approach taken by this plugin will not enable containers to resolve accross `docker-compose` projects. Name resolution inside containers uses DNS and bypasses the host system's NSS.\nTo solve this particular need, a possible solution would be to use `docker-compose`'s shared network (introduced with configuration file version 3.5, `docker-compose` version ):\n\nIn project A:\n```yaml\nservices:\n  serviceA:\n    networks:\n      shared:\n\nnetworks:\n  shared:\n    name: shared\n```\n\nIn project B:\n```yaml\nservices:\n  serviceB:\n    networks:\n      shared:\n\nnetworks:\n  shared:\n    name: shared\n```\nNote the `name: shared` parameters. This might seem redundant, but it ensures the network gets created with the same name, since `docker-compose` would otherwise prefix it with the project name.\n\nThis should enable you to resolve and access `serviceB` from `serviceA` and vice versa.\n\n### Memory consumption\n\nThis version of the plugin is written in Go, which means an automatic significant increase in memory usage. A future version may be rewritten in pure C to avoid this.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcostela%2Fnss-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcostela%2Fnss-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcostela%2Fnss-docker/lists"}