Skip to content

Usage

Jump to bottom
Nicholas St. Germain edited this page Jan 22, 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. command line options are kebab-case and environment variables are SCREAMING_CASE. E.g. --docker-sockets vs. DOCKER_SOCKETS. All examples will be given as environment variables for a docker run as --help will show command line examples

Help

Type: Boolean - Interrupting
Command Line: -h, --help

Shows the help message then exits

Core

Version

Type: Boolean - Interrupting
Command Line: -v, --version

Shows the current version number then exits

Docker Sockets

Type: List - Space separated
Command Line: -d, --docker-sockets
Environment Variable: DOCKER_SOCKETS
Example: -e DOCKER_SOCKETS="unix://var/run/docker.sock tcp://192.168.1.100:2376"

Allows you to define a list of docker sockets. If defined, it does not include the local socket by default.

Interval

Type: Integer
Command Line: -i, --interval
Environment Variable: INTERVAL
Example: -e INTERVAL=300

The interval in seconds between checking for updates. There is a hard-coded 30 second minimum. Anything lower than that will set to 30.

-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.

```bash
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