Skip to content

Usage

Jump to bottom
Caleb Lemoine edited this page Jan 18, 2019 · 37 revisions

Command line arguments can be viewed by running:

docker run --rm pyouroboros/ouroboros --help

Options

All command line arguments can be substituted with an environment variable

usage: ouroboros [-h] [-v] [-d DOCKER_SOCKETS [DOCKER_SOCKETS ...]]
                 [-i INTERVAL] [-l {debug,info,warn,error,critical}] [-u] [-o]
                 [-m MONITOR [MONITOR ...]] [-n IGNORE [IGNORE ...]] [-c] [-L]
                 [-r REPO_USER] [-R REPO_PASS] [-D {prometheus,influxdb}]
                 [-a PROMETHEUS_ADDR] [-p PROMETHEUS_PORT] [-I INFLUX_URL]
                 [-P INFLUX_PORT] [-U INFLUX_USERNAME] [-x INFLUX_PASSWORD]
                 [-X INFLUX_DATABASE] [-s] [-V]
                 [-w WEBHOOK_URLS [WEBHOOK_URLS ...]] [-y PUSHOVER_TOKEN]
                 [-Y PUSHOVER_DEVICE] [-z PUSHOVER_USER] [-e SMTP_HOST]
                 [-E SMTP_PORT] [-f] [-F SMTP_USERNAME] [-g SMTP_PASSWORD]
                 [-G SMTP_RECIPIENTS [SMTP_RECIPIENTS ...]]
                 [-j SMTP_FROM_EMAIL] [-J SMTP_FROM_NAME]

ouroboros

optional arguments:
  -h, --help            show this help message and exit

Core:
  Configuration of core functionality

  -v, --version         show program's version number and exit
  -d DOCKER_SOCKETS [DOCKER_SOCKETS ...], --docker-sockets DOCKER_SOCKETS [DOCKER_SOCKETS ...]
                        Sockets for docker management
                        DEFAULT: "unix://var/run/docker.sock"
                        EXAMPLE: -d unix://var/run/docker.sock tcp://192.168.1.100:2376
  -i INTERVAL, --interval INTERVAL
                        Interval in seconds between checking for updates
                        DEFAULT: 300
  -l {debug,info,warn,error,critical}, --log-level {debug,info,warn,error,critical}
                        Set logging level
                        DEFAULT: info
  -u, --self-update     Let ouroboros update itself
  -o, --run-once        Single run

Docker:
  Configuration of docker functionality

  -m MONITOR [MONITOR ...], --monitor MONITOR [MONITOR ...]
                        Which container(s) to monitor
                        DEFAULT: All
  -n IGNORE [IGNORE ...], --ignore IGNORE [IGNORE ...]
                        Container(s) to ignore
                        EXAMPLE: -n container1 container2
  -c, --cleanup         Remove old images after updating
  -L, --latest          Check for latest image instead of pulling current tag
  -r REPO_USER, --repo-user REPO_USER
                        Private docker registry username
                        EXAMPLE: foo@bar.baz
  -R REPO_PASS, --repo-pass REPO_PASS
                        Private docker registry password
                        EXAMPLE: MyPa$$w0rd

Data Export:
  Configuration of data export functionality

  -D {prometheus,influxdb}, --data-export {prometheus,influxdb}
                        Enable exporting of data for chosen option
  -a PROMETHEUS_ADDR, --prometheus-addr PROMETHEUS_ADDR
                        Bind address to run Prometheus exporter on. Has no effect without --data-export prometheus
                        DEFAULT: 127.0.0.1
  -p PROMETHEUS_PORT, --prometheus-port PROMETHEUS_PORT
                        Port to run Prometheus exporter on. Has no effect without --data-export prometheus
                        DEFAULT: 8000
  -I INFLUX_URL, --influx-url INFLUX_URL
                        URL for influxdb, Has no effect without --data-export influxdb
                        DEFAULT: 127.0.0.1
  -P INFLUX_PORT, --influx-port INFLUX_PORT
                        PORT for influxdb, Has no effect without --data-export influxdb
                        DEFAULT: 8086
  -U INFLUX_USERNAME, --influx-username INFLUX_USERNAME
                        Username for influxdb, Has no effect without --data-export influxdb
                        DEFAULT: root
  -x INFLUX_PASSWORD, --influx-password INFLUX_PASSWORD
                        Password for influxdb, Has no effect without --data-export influxdb
                        DEFAULT: root
  -X INFLUX_DATABASE, --influx-database INFLUX_DATABASE
                        Database for influxdb, Required if using influxdb. Has no effect without --data-export influxdb.
                        DEFAULT: root
  -s, --influx-ssl      Use SSL when connecting to influxdb
  -V, --influx-verify-ssl
                        Verify SSL certificate when connecting to influxdb

Notifications:
  Configuration of notification functionality

  -w WEBHOOK_URLS [WEBHOOK_URLS ...], --webhook-urls WEBHOOK_URLS [WEBHOOK_URLS ...]
                        Webhook POST urls
                        EXAMPLE: -w https://domain.tld/1234/asdf http://123.123.123.123:4040/re235
  -y PUSHOVER_TOKEN, --pushover-token PUSHOVER_TOKEN
                        Pushover token to authenticate against application
                        EXAMPLE: -y af2r52352asd
  -Y PUSHOVER_DEVICE, --pushover-device PUSHOVER_DEVICE
                        Device to receive pushover notification
                        EXAMPLE: -Y SamsungGalaxyS8
  -z PUSHOVER_USER, --pushover-user PUSHOVER_USER
                        Pushover user bound to application
                        EXAMPLE: -z asdfweawefasdfawef
  -e SMTP_HOST, --smtp-host SMTP_HOST
                        SMTP relay hostname
                        EXAMPLE: -e smtp.gmail.com
  -E SMTP_PORT, --smtp-port SMTP_PORT
                        SMTP relay port
                        EXAMPLE: -E 587
  -f, --smtp-starttls   SMTP relay uses STARTTLS
  -F SMTP_USERNAME, --smtp-username SMTP_USERNAME
                        SMTP relay username
                        EXAMPLE: -F ouroboros@ouroboros.com
  -g SMTP_PASSWORD, --smtp-password SMTP_PASSWORD
                        SMTP relay password
                        EXAMPLE: -g MyPa$$w0rd
  -G SMTP_RECIPIENTS [SMTP_RECIPIENTS ...], --smtp-recipients SMTP_RECIPIENTS [SMTP_RECIPIENTS ...]
                        SMTP notification recipients
                        EXAMPLE: -G ouroboros@ouroboros.com ouroboros2@ouroboros.com
  -j SMTP_FROM_EMAIL, --smtp-from-email SMTP_FROM_EMAIL
                        SMTP from email
                        EXAMPLE: -g notifications@ouroboros.com
  -J SMTP_FROM_NAME, --smtp-from-name SMTP_FROM_NAME
                        SMTP from name
                        DEFAULT: Ouroboros

EXAMPLE: ouroboros -d tcp://1.2.3.4:5678 -i 20 -m container1 container2 -l warn

Config File

You can provide a docker env file to supplement a config file with all the above listed arguments by utilizing the supported environment variables.

docker run -d --name ouroboros \
  --env-file env.list \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros

Sample env.list:

DOCKER_SOCKETS=tcp://localhost:2375
INTERVAL=60
MONITOR="container_1 container_2"

Docker Compose

version: '3'
services:
  nginx:
    image: nginx:1.14-alpine
    ports:
     - 80:80
  ouroboros:
    image: pyouroboros/ouroboros
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 60 --log-level debug
    environment:
    - REPO_USER=user
    - REPO_PASS=password

Examples

Change update frequency

An interval argument can be supplied to change how often ouroboros checks the remote docker registry for image updates (in seconds).

Default is 300s

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --interval 600

Monitor select containers

By default, ouroboros will monitor all running docker containers, but can be overridden to only monitor select containers by passing a monitor argument which supports an infinite amount of container names.

Default is all

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --monitor container_1 container_2 container_3

Ignore select containers

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --ignore container_1 container_2 container_3

Change loglevel

The amount of logging details can be suppressed by providing a log-level argument.

Default is info

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --log-level debug

Update all containers and quit ouroboros

If you prefer ouroboros didn't run all the time and only update all of your running containers in one go, provide the run-once argument and ouroboros will terminate itself after updating all your containers one time.

Default is False

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --run-once

Remove old docker images

Ouroboros has the option to remove the older docker image if a new one is found and the container is then updated. To tidy up after updates, pass the cleanup argument.

Default is False

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --cleanup

Prometheus metrics

Ouroboros keeps track of containers being updated and how many are being monitored. Said metrics are exported using prometheus. You can also bind the http server to a different interface for systems using multiple networks. --prometheus-port and --prometheus-addr can run independently of each other without issue.

Prometheus exporter will not be reachable by default inside of a container. You will need to intentionally bind to 0.0.0.0 for docker network interfaces to be able to reach the exporter the host network. This was done intentionally for security reasons.

Bind Address & Port

Bind Address default is 127.0.0.1

Port Default is 8000

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 pyouroboros/ouroboros --data-export prometheus --prometheus-addr 0.0.0.0

You should then be able to see the metrics at http://localhost:8000/

Example text from endpoint:

# HELP containers_updated_total Count of containers updated
# TYPE containers_updated_total counter
containers_updated_total{container="all"} 2.0
containers_updated_total{container="alpine"} 1.0
containers_updated_total{container="busybox"} 1.0
# TYPE containers_updated_created gauge
containers_updated_created{container="all"} 1542152615.625264
containers_updated_created{container="alpine"} 1542152615.6252713
containers_updated_created{container="busybox"} 1542152627.7476819
# HELP containers_being_monitored Count of containers being monitored
# TYPE containers_being_monitored gauge
containers_being_monitored 2.0

Webhook Notifications

See the notifications wiki for more details.

Default is None

docker run -d --name ouroboros \
 -v /var/run/docker.sock:/var/run/docker.sock \
 pyouroboros/ouroboros --webhook-urls https://hooks.slack.com/something https://discordapp.com/api/webhooks/something

Clone this wiki locally