{"id":29258371,"url":"https://github.com/ninjken/dynamic_file_upstreams","last_synced_at":"2026-04-24T11:31:51.300Z","repository":{"id":302244627,"uuid":"1000747320","full_name":"ninjken/dynamic_file_upstreams","owner":"ninjken","description":"nginx file-based dynamic upstreams","archived":false,"fork":false,"pushed_at":"2025-07-01T09:29:28.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-01T10:37:33.756Z","etag":null,"topics":["dynamic","file-based","nginx","upstream"],"latest_commit_sha":null,"homepage":"","language":"C","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/ninjken.png","metadata":{"files":{"readme":"README.markdown","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T09:02:59.000Z","updated_at":"2025-07-01T09:29:31.000Z","dependencies_parsed_at":"2025-07-01T10:38:20.852Z","dependency_job_id":"33726160-6d1b-4d09-8c75-ab1fdc694ad9","html_url":"https://github.com/ninjken/dynamic_file_upstreams","commit_stats":null,"previous_names":["ninjken/dynamic_file_upstreams"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ninjken/dynamic_file_upstreams","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninjken%2Fdynamic_file_upstreams","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninjken%2Fdynamic_file_upstreams/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninjken%2Fdynamic_file_upstreams/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninjken%2Fdynamic_file_upstreams/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ninjken","download_url":"https://codeload.github.com/ninjken/dynamic_file_upstreams/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninjken%2Fdynamic_file_upstreams/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263457106,"owners_count":23469279,"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":["dynamic","file-based","nginx","upstream"],"created_at":"2025-07-04T06:00:54.500Z","updated_at":"2026-04-24T11:31:51.292Z","avatar_url":"https://github.com/ninjken.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Table of Contents\n- Name\n- Description\n- Status\n- Synopsis\n- Directives\n- Caveats and Limitations\n- Compatibiliy with Nginx version\n- Installation\n- Testing\n- Author\n- License\n- TODO\n \n## Name\nngx_dynamic_file_upstreams_module\n\n## Description\nNginx is a famous high permormance reverse proxy and HTTP server. However, its conspicuous lack of ability to modify its configuration at runtime (without reloading) makes it unfit for highly dynamic HTTP environments. Dynamic upstream support is one of the common difficulties. There are already some very good solutions to address this difficulty\n\n1. `balancer_by_lua` from the [ngx_lua module](http://github.com/openresty/lua-nginx-module) is a powerful way to set upstream servers in lua script\n2. [ngx_dynamic_upstream](https://github.com/cubicdaiya/ngx_dynamic_upstream) module exposes HTTP API for upstream modification\n3. [nginx-upsync-module](https://github.com/weibocom/nginx-upsync-module) achieves this by making use of Consul/Etcd\n\nngx_dynamic_file_upstreams_module, however, takes a file-based approach and have nginx parse an upstreams text file when it is modified and automatically reload upstreams defined in it.\n\n## Status\nthis module is not production-ready yet, more work wants to be done\n\n## Synopsis\nNginx configuration\n\n```nginx\nhttp {\n    upstream test_upstream {\n        zone test 256k;\n        server 1.2.3.4:8080 weight=1 max_conns=100;\n        server 1.2.3.4:8082 fail_timeout=1m weight=1 max_conns=100;\n        server 5.6.7.8 down;\n    }\n\n    upstreams_file /opt/nginx/test_upstreams_file interval=15s;\n\n    server {\n        listen 8090;\n        location / {\n            proxy_pass http://test_upstream;\n        }\n    }\n}\n```\n\nwith */opt/nginx/test_upstream_file*\n\n```txt\nupstream test_upstream {\n    #this is a demonstration file\n    server 127.0.0.1:8080 weight=1 max_conns=100;\n    server 127.0.0.1:8082 weight=1 fail_timeout=1m max_conns=1000 backup;\n    server unix:/tmp/backend3 down;\n}\n\nupstream test_upsteam2 {\n    ...\n}\n```\n\nthe format of upstreams file is basically the same as Nginx upstream block, except that only *server* line is allowed (zone and upstream load-balance method are disallowed).\n\n## Directives\n\n`upstreams_file /path/to/upstreams_file interval=time`\n\nwhere time is any valid time interval supported by Nginx, see https://nginx.org/en/docs/syntax.html#time.\n\nThe default unit is second.\n\n## Caveats and Limitations\nOnly upstreams which are already defined in the original Nginx configuration can be specified in the upstream file. In other words, one cannot add new upstreams at runtime(existing upstreams, if not specified in the upstream file, will not get deleted and stay untouched)\n\n## Compatibiliy with Nginx version\nTested with Nginx version 1.29.0 on Linux, earlier versions should work just fine. Windows platform is not yet tested.\n\n## Installation\nPlease follow standard module compilation step\n\n    ./auto/configure --add-module=/path/to/module_dir\n\nor\n\n    ./auto/configure --add-dynamic-module=/path/to/module_dir\n\nthen\n\n    make\n\nFor dynamic module build, there will be *ngx_dynamic_file_upstreams_module.so* in folder objs/ which can be loaded by nginx via 'load_module' directive.\n\n## Testing\nTests are based on [nginx-tests](github.com:nginx/nginx-tests.git), test files are in folder t/ and are written, you know, in Perl.\n\n## Author\nninjken endeavourken@outlook.com\n\nPlease raise issues if you find any problem :-).\n\n## License\nMIT License.\n\n## TODO\n- add more tests, regarding different load balance methods and upstream server options such as fail_timeout and max_fails.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninjken%2Fdynamic_file_upstreams","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fninjken%2Fdynamic_file_upstreams","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninjken%2Fdynamic_file_upstreams/lists"}