diff --git a/README.md b/README.md index b8266ac..c3960ca 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ phpIPAM is developed and maintained by Miha Petkovsek, released under the GPL v3 Learn more on [phpIPAM homepage](http://phpipam.net) -This container can be used as a discovery scan agent. +This container can be used as a remote discovery scan agent. ## How to use this Docker image @@ -18,43 +18,59 @@ This container can be used as a discovery scan agent. * For each subnet, enable scan & configure the remote agent by selecting a remote. ![config_subnet](https://user-images.githubusercontent.com/4225738/45190619-2ba94f00-b23f-11e8-9e45-b5e721c63d70.png) -## Scheduled scans +### Setup database -For scheduled scans these commands are added to the cron script. -```bash -1/15 * * * * /usr/local/bin/php /opt/phpipam-agent/index.php update -1/15 * * * * /usr/local/bin/php /opt/phpipam-agent/index.php discover +* Configure MySQL/MariaDB to [listen for incoming connections](https://mariadb.com/kb/en/configuring-mariadb-for-remote-client-access/) (not bind to loopback) + +* Grant remote access to the database: ``` +$ mysql -u root -p +> GRANT SELECT on `phpipam`.* TO 'username'@'192.168.1.%' identified by "securePasswordHere"; +> GRANT INSERT on `phpipam`.* TO 'username'@'192.168.1.%' identified by "securePasswordHere"; +> GRANT UPDATE on `phpipam`.* TO 'username'@'192.168.1.%' identified by "securePasswordHere"; +> GRANT DELETE on `phpipam`.* TO 'username'@'192.168.1.%' identified by "securePasswordHere"; +``` +*Use `%` as a wildcard. `'phpipam'@'192.168.1.%'` would allow the user `phpipam` to access the database from any host on the `192.168.1.0/24` network. `'phpipam'@'%'` would let that user in from ANY host.* -## Run this container +### Run this container ```bash -version: '2' +version: '3' services: phpipam-agent: container_name: phpipam-agent restart: unless-stopped - image: mc303/phpipam-agent:latest + image: jbowdre/phpipam-agent:latest environment: - - MYSQL_ENV_MYSQL_HOST=10.10.1.10 - - MYSQL_ENV_MYSQL_DATABASE=phpipam - - MYSQL_ENV_MYSQL_USER=phpipam - - MYSQL_ENV_MYSQL_PASSWORD=phpipam - - MYSQL_ENV_MYSQL_PORT=3307 - - PHPIPAM_AGENT_KEY=abcder1223456xczxcsad - - CRON_SCHEDULE=1/15 * * * * - - TZ=Europe/Amsterdam - ports: - - "3306:3306" + - PHPIPAM_DB_HOST=ipamhost.local + - PHPIPAM_DB_NAME=phpipam + - PHPIPAM_DB_USER=phpipam + - PHPIPAM_DB_PASS=phpipamadmin + - PHPIPAM_DB_PORT=3306 + - PHPIPAM_AGENT_KEY=2RuQ0rt4Rir29vGN4_1ZOqShcUX7PSUb + - PHPIPAM_SCAN_INTERVAL=15m + - PHPIPAM_RESET_AUTODISCOVER=false + - PHPIPAM_REMOVE_DHCP_false + - TZ=UTC ``` -Now, the update/discovery scans will be performed every X minute defined by CRON_SCHEDULE environment variable. +## Configuration Parameters +| Parameter | Description | +| --- | --- | +| `PHPIPAM_DB_HOST` | IP/FQDN where the phpIPAM database is running | +| `PHPIPAM_DB_NAME` | Name of the database on the host *(Optional; default: `phpipam`)* | +| `PHPIPAM_DB_USER` | Database user with required privileges *(Optional; default: `phpipam`)* | +| `PHPIPAM_DB_PASS` | Password for that user | +| `PHPIPAM_DB_PORT` | Port number for the database listener *(Optional; default: `3306`)* | +| `PHPIPAM_AGENT_KEY` | Unique key generated by phpIPAM for each scan agent | +| `PHPIPAM_SCAN_INTERVAL` | How frequently the Status and Discovery scans will run (Valid options: `5m`, `10m`, `15m`, `30m`, `1h`, `2h`, `4h`, `6h`, `12h`) *(Optional; default: `15m`)* | +| `PHPIPAM_RESET_AUTODISCOVER` | Enable the agent to remove autodiscovered IPs which are offline *(Optional; default: `false`)* | +| `PHPIPAM_REMOVE_DHCP` | Enable the agent to remove inactive DHCP addresses *(Optional; default: `false`)* | +## Logging The logs are available on stdout/stderr (allowing to use `docker logs`). -# Acknowledgements +## Acknowledgements -Based on [pierrecdn/phpipam-agent](https://github.com/pierrecdn/phpipam-agent), [published on docker hub](https://hub.docker.com/r/pierrecdn/phpipam-agent). +Based on [mc303/phpipam-agent](https://github.com/mc303/phpipam-agent) which is based on[pierrecdn/phpipam-agent](https://github.com/pierrecdn/phpipam-agent) and [published on docker hub](https://hub.docker.com/r/pierrecdn/phpipam-agent). - -## phpipam-agent