- Description
- Reference API
- Prerequisites
- Installation
- Settings
- Usage
- Options
- Examples
- Important Notice
- TODO
Warning
The --restore command is disabled (a fix is in progress).
🛠️ This script allows you to efficiently manage Nginx Proxy Manager via its API. It provides advanced features such as proxy host creation, user management, and configuration display, while also integrating a backup system (BACKUP) with a user-friendly interface.
It simplifies task automation, including proxy creation, SSL certificate management, and full reverse proxy administration.
🔑 Automatically generates and manages tokens, ensuring their validity, so you don't have to worry about token expiration.
French description:
Ce script permet de gérer Nginx Proxy Manager via son API de manière simple et efficace. Il offre des fonctionnalités avancées telles que la création de hosts proxy, la gestion des utilisateurs et l'affichage des configurations, tout en intégrant un système de sauvegarde (BACKUP) avec une interface conviviale.Il facilite l'automatisation des tâches courantes, comme l'ajout de proxies, la gestion des certificats SSL et l'administration complète de vos reverse proxies.
https://github.com/NginxProxyManager/nginx-proxy-manager/tree/develop/backend/schema
The excellent NPM ()
Required basic dependencies.
The script will automatically check if they are installed and will download them if necessary:curljq
wget https://raw.githubusercontent.com/Erreur32/nginx-proxy-manager-Bash-API/main/npm-api.sh chmod +x npm-api.sh # Run the script. ./npm-api.shImportant
(Optional) You can create a configuration file named npm-api.conf with these 4 required variables.
To ensure the script is functional, edit these 4 variables (mandatory).
# npm-api.conf ## Nginx proxy IP address (your Nginx IP/port) NGINX_IP="127.0.0.1" NGINX_PORT="81" ## Existing user (user and password) on NPM API_USER="admin@example.com" API_PASS="changeme" # Optional (only if you want in other /path than script directory) # DATA_DIR="/path/nginx_backup/dir" ./npm-api.sh [OPTIONS] ./npm-api.sh --help ./npm-api.sh --show-default 📊 NGINX - Proxy Manager - Dashboard 🔧 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ┌─────────────────┬─────────┐ │ COMPONENT │ STATUS │ ├─────────────────┼─────────┤ │ 🌐 Proxy Hosts │ 11 │ │ ├─ Enabled │ 9 │ │ └─ Disabled │ 2 │ ├─────────────────┼─────────┤ │ 🔄 Redirections │ 1 │ │ 🔌 Stream Hosts │ 0 │ ├─────────────────┼─────────┤ │ 🔒 Certificates │ 1 │ │ ├─ Valid │ 1 │ │ └─ Expired │ 0 │ ├─────────────────┼─────────┤ │ 🔒 Access Lists │ 1 │ │ └─ Clients │ 0 │ ├─────────────────┼─────────┤ │ 👥 Users │ 3 │ ├─────────────────┼─────────┤ │ ⏱️ Uptime │ 2 days │ │ 📦 NPM Version │ 2.12.3 │ └─────────────────┴─────────┘ 💡 Use --help to see available commands Check --examples for more help examples 🌐 Host proxy creation: -d DOMAIN_NAMES Domain name (required for creating/updating hosts) -i FORWARD_HOST IP address or domain name of the target server (required for creating/updating hosts) -p FORWARD_PORT Port of the target server (required for creating/updating hosts) -f FORWARD_SCHEME Scheme for forwarding (http/https, default: http) -c CACHING_ENABLED Enable caching (true/false, default: false) -b BLOCK_EXPLOITS Block exploits (true/false, default: true) -w ALLOW_WEBSOCKET_UPGRADE Allow WebSocket upgrade (true/false, default: true) -l CUSTOM_LOCATIONS Custom locations (JSON array of location objects) -a ADVANCED_CONFIG Advanced configuration (block of configuration settings) -y Automatic yes prompts, yes sir! 📦 Backup and Restore: --backup Backup all configurations to a file --backup-host id Backup a single host configuration and its certificate (if exists) 🔧 Miscellaneous: --check-token Check if the current token is valid --create-user user pass email Create a user with a username, password and email --delete-user username Delete a user by username --host-delete id Delete a proxy host by ID --host-show id Show full details for a specific host by ID --show-default Show default settings for creating hosts --host-list List the names of all proxy hosts --host-list-full List all proxy hosts with full details --list-users List all users --host-search hostname Search for a proxy host by domain name --host-enable id Enable a proxy host by ID --host-disable id Disable a proxy host by ID --host-ssl-enable id Enable SSL, HTTP/2, and HSTS for a proxy host --host-ssl-disable id Disable SSL, HTTP/2, and HSTS for a proxy host --list-ssl-cert List All SSL certificates availables (JSON) --cert-generate domain email Generate certificate for the given domain and email --delete-cert domain Delete certificate for the given domain --list-access List all available access lists (ID and name) --host-acl-enable id,access_list_id Enable ACL for a proxy host by ID with an access list ID --host-acl-disable id Disable ACL for a proxy host by ID --update-host id field=value Modify any field on existing entry host --help Display this help 📦 Backup First ! ./npm-api.sh --backup 🌐 Host Creation: # Basic host creation ./npm-api.sh --host-create example.com -i 192.168.1.10 -p 8080 # Create host with SSL certificate and enable SSL (all-in-one) ./npm-api.sh --host-create sub.domain.com -i 192.168.0.1 -p 80 --cert-generate --host-ssl-enable -y # Create host with custom options ./npm-api.sh --host-create example.com -i 192.168.1.10 -p 8080 \ -f https \ # Forward scheme -b true \ # Block exploits -c true \ # Enable caching -w true \ # Enable websocket -y # Auto confirm 🤖 Automatic operations (no prompts): ./npm-api.sh --host-create example.com -i 192.168.1.10 -p 8080 -y ./npm-api.sh --host-delete 42 -y ./npm-api.sh --host-ssl-enable 10 -y 🔍 Information and Status: ./npm-api.sh --info # Show configuration and dashboard ./npm-api.sh --show-default # Show default settings ./npm-api.sh --check-token # Verify token validity ./npm-api.sh --host-search domain.com # Search for a specific domain ./npm-api.sh --host-list # List all hosts ./npm-api.sh --host-list-full # List hosts with details ./npm-api.sh --host-show 42 # Show specific host details 🔒 SSL Management: # List all certificates ./npm-api.sh --list-ssl-cert # Generate standard Let's Encrypt certificate ./npm-api.sh --cert-generate example.com --cert-email admin@example.com # Generate wildcard certificate with Cloudflare ./npm-api.sh --cert-generate "*.example.com" \ --cert-email admin@example.com \ --dns-provider cloudflare \ --dns-credentials '{"dns_cloudflare_email":"your@email.com","dns_cloudflare_api_key":"your_api_key"}' # Delete certificate ./npm-api.sh --delete-cert domain.com # Enable SSL for host ./npm-api.sh --host-ssl-enable 42 # Enable SSL with specific cert ID ./npm-api.sh --host-ssl-enable 42 33 🌟 Complete Examples with Wildcard Certificates: # Create host with wildcard certificate using Cloudflare DNS ./npm-api.sh --host-create "*.example.com" -i 192.168.1.10 -p 8080 \ --cert-generate "*.example.com" \ --cert-email admin@example.com \ --dns-provider cloudflare \ --dns-credentials '{"dns_cloudflare_email":"your@email.com","dns_cloudflare_api_key":"your_api_key"}' \ --host-ssl-enable -y # Same with DigitalOcean DNS ./npm-api.sh --host-create "*.example.com" -i 192.168.1.10 -p 8080 \ --cert-generate "*.example.com" \ --cert-email admin@example.com \ --dns-provider digitalocean \ --dns-credentials '{"dns_digitalocean_token":"your_token"}' \ --host-ssl-enable -y # Same with GoDaddy DNS ./npm-api.sh --host-create "*.example.com" -i 192.168.1.10 -p 8080 \ --cert-generate "*.example.com" \ --cert-email admin@example.com \ --dns-provider godaddy \ --dns-credentials '{"dns_godaddy_key":"your_key","dns_godaddy_secret":"your_secret"}' \ --host-ssl-enable -y 🛡️ Access Control Lists: ./npm-api.sh --list-access # List all access lists ./npm-api.sh --host-acl-enable 42,5 # Enable ACL ID 5 for host 42 ./npm-api.sh --host-acl-disable 42 # Disable ACL for host 42 👥 User Management: ./npm-api.sh --create-user newuser password123 user@example.com ./npm-api.sh --delete-user 'username' ./npm-api.sh --list-users 🔧 Advanced Examples: # Custom Nginx configuration ./npm-api.sh --host-create example.com -i 192.168.1.10 -p 8080 \ -a 'proxy_set_header X-Real-IP $remote_addr;' 🛡️ Custom locations: ./npm-api.sh --host-create example.com -i 192.168.1.10 -p 8080 \ -l '[{"path":"/api","forward_host":"192.168.1.11","forward_port":8081}]' # Update specific fields ./npm-api.sh --update-host 42 forward_scheme=https ./npm-api.sh --update-host 42 forward_port=8443 🔖 Full options: ./npm-api.sh --host-create example.com -i 192.168.1.10 -p 8080 -f https -c true -b true -w true -a 'proxy_set_header X-Real-IP $remote_addr;' -l '[{"path":"/api","forward_host":"192.168.1.11","forward_port":8081}]'./npm-api.sh --backup# Full backup of all configurations ./npm-api.sh --backup # This will create a backup in the following structure: 📁 data/ └── 📁 backups/ └── 📁 [IP]_[PORT]/ ├── 📁 .access_lists/ # Access list configurations ├── 📁 .Proxy_Hosts/ # All proxy host configurations │ ├── 📁 [DOMAIN]/ # Directory for each domain │ │ ├── 📁 logs/ # Log directory │ │ ├── 📁 ssl/ # SSL directory │ │ │ ├── 📄 certificate_meta.json # Certificate metadata │ │ │ ├── 📄 certificate.pem # Certificate │ │ │ ├── 📄 chain.pem # Chain of certificates │ │ │ └── 📄 private.key # Private key │ │ ├── 📄 nginx.conf # Nginx configuration │ │ └── 📄 proxy_config.json # Proxy configuration │ ├── 📄 all_hosts_[DATE].json # List of all hosts │ └── 📄 all_hosts_latest.json # Symlink to latest backup ├── 📁 .settings/ # NPM settings ├── 📁 .ssl/ # SSL certificates ├── 📁 .user/ # User configurations └── 📄 full_config.json # Complete backup file └── 📁 token/ ├── 📄 token.txt # Authentication token └── 📄 expiry.txt # Token expiry date -
Proxy Hosts (
/.Proxy_Hosts/)- Individual host configurations
- Nginx configurations
- Complete host list with timestamps
-
SSL Certificates (
/.ssl/)- Certificates and private keys
- Certificate metadata
- Chain certificates
-
Access Lists (
/.access_lists/)- Access list configurations
- Client authorizations
- Access rules
-
Users (
/.user/)- User accounts
- Permissions
- Authentication settings
-
Settings (
/.settings/)- Global NPM settings
- System configurations
- Default parameters
The token/ directory contains:
- Authentication tokens
- Token expiry information
- One file per NPM instance
The --host-update command allows you to update specific fields of an existing proxy host in Nginx Proxy Manager without recreating it.
Simply specify the proxy host ID and the field you want to update, like this:
./npm-api.sh --update-host 42 forward_host=new.backend.local| Field Name | Type | Description |
|---|---|---|
domain_names | array | List of domains handled by this proxy. |
forward_host | string | The destination (backend) hostname or IP. |
forward_port | integer | The destination port (e.g., 8000, 443). |
forward_scheme | string | The scheme: http or https. |
enabled | boolean | Whether the proxy is enabled (true or false). |
ssl_forced | boolean | Redirect all HTTP requests to HTTPS. |
certificate_id | integer | The ID of the SSL certificate to use. |
meta.letsencrypt_agree | boolean | Agree to Let's Encrypt TOS (true or false). |
meta.dns_challenge | boolean | Use DNS challenge for SSL cert (true or false). |
allow_websocket_upgrade | boolean | Enable WebSocket support (true or false). |
http2_support | boolean | Enable HTTP/2 (true or false). |
caching_enabled | boolean | Enable caching (true or false). |
block_exploits | boolean | Block known exploits (true or false). |
advanced_config | string | Custom Nginx directives (multiline string). |
locations | array | Custom location blocks (advanced use). |
Some info of settings in the script with ./npm-api.sh --info
./npm-api.sh --info 🔍 Checking system dependencies and directories... ✅ All dependencies and directories are properly set up ├── System tools: OK ├── Directories : OK └── Permissions : OK 🔑 Checking token validity... ✅ Token is valid 📅 Expires: 2026-03-14T10:24:56.267Z Script Info: 3.0.0 Script Variables Information: Config : /home/tools/Project/nginx_proxy/npm-api.conf BASE URL : http://127.0.0.1:8099/api NGINX IP : 127.0.0.1 USER NPM : user@mail.com BACKUP DIR : /home/tools/Project/nginx_proxy/data/127_0_0_1_8099 📂 Backup Locations: • Backup: /home/tools/Project/nginx_proxy/data/127_0_0_1_8099/backups • Token: /home/tools/Project/nginx_proxy/data/127_0_0_1_8099/backups/token/ 📊 NGINX - Proxy Manager - Dashboard 🔧 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ┌─────────────────┬─────────┐ │ COMPONENT │ STATUS │ ├─────────────────┼─────────┤ │ 🌐 Proxy Hosts │ 11 │ │ ├─ Enabled │ 9 │ │ └─ Disabled │ 2 │ ├─────────────────┼─────────┤ │ 🔄 Redirections │ 1 │ │ 🔌 Stream Hosts │ 0 │ ├─────────────────┼─────────┤ │ 🔒 Certificates │ 1 │ │ ├─ Valid │ 1 │ │ └─ Expired │ 0 │ ├─────────────────┼─────────┤ │ 🔒 Access Lists │ 1 │ │ └─ Clients │ 0 │ ├─────────────────┼─────────┤ │ 👥 Users │ 3 │ ├─────────────────┼─────────┤ │ ⏱️ Uptime │ 2 days │ │ 📦 NPM Version │ 2.12.3 │ └─────────────────┴─────────┘ 💡 Use --help to see available commands Check --examples for more help examplesBy following these steps, you can enable SSL for your proxy host for the first time using Let's Encrypt.
List all Host in one command and show ´id´ , ´status´ and ´SSL´ status:
./npm-api.sh --host-list 👉 List of proxy hosts (simple) ID Domain Status SSL Certificate Domain 14 example.com enabled ✘ 15 example.titi enabled ✘ 1 domain.com disable 8 domain.com 11 titi.eu enabled ✘ 12 toutou disable ✘ 13 toutoux enabled ✘ Assuming the host ID is 1, you would enable SSL for the host as follows:
./npm-api.sh --host-ssl-enable 1 Host proxy info command --host-show id
./npm-api.sh --host-show 1 👉 Full details for proxy host ID: 59... { "id": 10, "created_on": "2024-07-11 13:16:34", "modified_on": "2024-07-13 09:42:40", "owner_user_id": 1, "domain_names": [ "test.domain.com" ], "forward_host": "127.0.0.1", "forward_port": 80, "access_list_id": 0, "certificate_id": 81, "ssl_forced": 1, "caching_enabled": 0, "block_exploits": 1, "advanced_config": "", "meta": { "letsencrypt_agree": true, "letsencrypt_email": "", "nginx_online": true, "nginx_err": null }, "allow_websocket_upgrade": 1, "http2_support": 1, "forward_scheme": "http", "enabled": 1, "locations": [], "hsts_enabled": 1, "hsts_subdomains": 0 } We have performed a force push (git push --force) on this repository to remove sensitive data from the history. As a result, the commit history has been rewritten, and your local copy may be out of sync.
🛠️ What You Need to Do? To avoid any issues, please follow these steps to update your local repository:
git fetch --all git reset --hard origin/main # Replace 'main' with your branch name if differentIf you have local changes that you don't want to lose, consider making a backup before running these commands.
❓ Why Was This Done? This action was necessary to remove sensitive data from the repository's history and ensure better security.
- add setting for ADVANCED configuration in npm
location / { ... } - Add documentation on certain functions
- ADD: a configuration function for Custom Locations
- Backup all settings from NPM
- Add automatic confirmation with -y parameter
- Clean/minimize output when using -y parameter for better script integration
- Creation of ACCESS list through CLI
- Restore Function not working properly, need to find FIX
Special thanks to:
- @ichbinder for implementing the
-yparameter for automatic confirmations
MIT License - see the LICENSE.md file for details