Merge pull request #417 from gliderlabs/master

release 3.2.6

Author: michaelshobbs

CHANGELOG.md

@@ -10,6 +10,23 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+## [v3.2.6] - 2018-10-04
+### Fixed
+- @jdgiotta Spelling corrections and fixed stack compose formatting in example
+- @dylanmei dylanmei Update 3rd party module link in README
+
+### Added
+- @vbeausoleil added a simple healthcheck
+- @gbolo added option to load TLS client certificate and key
+- @gbolo added ability to control the TLS client trust store
+- @gbolo added option to harden the TLS client
+- @chopmann added option to bind the http server to an address
+- @ibrokethecloud added ability to add custom key:value pairs as EXCLUDE_LABEL
+
+### Changed
+- @develar alpine 3.8 + golang 1.10.1
+- @gbolo enforced the use of `go 1.8+` in order to accommodate some TLS settings
+
 ## [v3.2.5] - 2018-06-05
 - @gmelika panic if reconnect fails
 - @masterada Added multiline adapter
@@ -182,7 +199,8 @@ All notable changes to this project will be documented in this file.
 - Base container is now Alpine
 - Moved to gliderlabs organization
 
-[unreleased]: https://github.com/gliderlabs/logspout/compare/v3.2.5...HEAD
+[unreleased]: https://github.com/gliderlabs/logspout/compare/v3.2.6...HEAD
+[v3.2.6]: https://github.com/gliderlabs/logspout/compare/v3.2.5...v3.2.6
 [v3.2.5]: https://github.com/gliderlabs/logspout/compare/v3.2.4...v3.2.5
 [v3.2.4]: https://github.com/gliderlabs/logspout/compare/v3.2.3...v3.2.4
 [v3.2.3]: https://github.com/gliderlabs/logspout/compare/v3.2.2...v3.2.3

Dockerfile

@@ -1,4 +1,4 @@
-FROM alpine:3.7
+FROM alpine:3.8
 ENTRYPOINT ["/bin/logspout"]
 VOLUME /mnt/routes
 EXPOSE 80

Dockerfile.dev

@@ -1,4 +1,4 @@
-FROM alpine:3.6
+FROM alpine:3.8
 VOLUME /mnt/routes
 EXPOSE 80
 

Makefile

@@ -71,6 +71,18 @@ test-tls:
 	docker stop $(NAME)-tls || true
 	docker rm $(NAME)-tls || true
 
+test-healthcheck:
+	docker run -d --name $(NAME)-healthcheck \
+		-p 8000:80 \
+		-v /var/run/docker.sock:/var/run/docker.sock \
+		$(NAME):$(VERSION)
+	sleep 2
+	docker logs $(NAME)-healthcheck
+	docker inspect --format='{{ .State.Running }}' $(NAME)-healthcheck | grep true
+	curl --head --silent localhost:8000/health | grep "200 OK"
+	docker stop $(NAME)-healthcheck || true
+	docker rm $(NAME)-healthcheck || true
+
 test-custom:
 	docker run --name $(NAME)-custom $(NAME):custom || true
 	docker logs $(NAME)-custom | grep -q logstash

README.md

@@ -97,7 +97,7 @@ You can tell logspout to only display log entries since container "start" or "re
 
 The default behaviour is to output all logs since creation of the container (equivalent to `docker logs --tail=all` or simply `docker logs`).
 
-> NOTE: Use of this option **may** cause the first few lines of log output to be missed following a container being started, if the container starts outputting logs before logspout has a chance to see them. If consistent capture of *every* line of logs is critical to your application, you might want to test thorougly and/or avoid this option (at the expense of getting the entire backlog for every restarting container). This does not affect containers that are removed and recreated.
+> NOTE: Use of this option **may** cause the first few lines of log output to be missed following a container being started, if the container starts outputting logs before logspout has a chance to see them. If consistent capture of *every* line of logs is critical to your application, you might want to test thoroughly and/or avoid this option (at the expense of getting the entire backlog for every restarting container). This does not affect containers that are removed and recreated.
 
 
 #### Environment variable, TAIL
@@ -157,7 +157,7 @@ Using the environment variable `MULTILINE_MATCH`=<first|last|nonfirst|nonlast> (
 * nonfirst: append all matching lines to first line and start over with the next non-matching line
 
 ##### Important!
-If you use multiline logging with raw, it's recommended to json encode the Data to avoid linebreaks in the output, eg:
+If you use multiline logging with raw, it's recommended to json encode the Data to avoid line breaks in the output, eg:
 
     "RAW_FORMAT={{ toJSON .Data }}\n"
 
@@ -167,8 +167,9 @@ If you use multiline logging with raw, it's recommended to json encode the Data
 * `BACKLOG` - suppress container tail backlog
 * `TAIL` - specify the number of lines in the log tail to capture when logspout starts (default `all`)
 * `DEBUG` - emit debug logs
-* `EXCLUDE_LABEL` - exclude logs with a given label
+* `EXCLUDE_LABEL` - exclude containers with a given label. The label can have a value of true or a custom value matched with : after the label name like label_name:label_value.
 * `INACTIVITY_TIMEOUT` - detect hang in Docker API (default 0)
+* `HTTP_BIND_ADDRESS` - configure which interface address to listen on (default 0.0.0.0)
 * `PORT` or `HTTP_PORT` - configure which port to listen on (default 80)
 * `RAW_FORMAT` - log format for the raw adapter (default `{{.Data}}\n`)
 * `RETRY_COUNT` - how many times to retry a broken socket (default 10)
@@ -238,34 +239,75 @@ networks:
   logging:
 services:
   logspout:
-  image: gliderlabs/logspout:latest
-  networks:
-    - logging
-  volumes:
-    - /etc/hostname:/etc/host_hostname:ro
-    - /var/run/docker.sock:/var/run/docker.sock
-  command:
-    syslog://svt2-logger.am2.cloudra.local:514
-  deploy:
-    mode: global
-    resources:
-      limits:
-        cpus: '0.20'
-        memory: 256M
-      reservations:
-        cpus: '0.10'
-      memory: 128M
+    image: gliderlabs/logspout:latest
+    networks:
+      - logging
+    volumes:
+      - /etc/hostname:/etc/host_hostname:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+    command:
+      syslog://svt2-logger.am2.cloudra.local:514
+    deploy:
+      mode: global
+      resources:
+        limits:
+          cpus: '0.20'
+          memory: 256M
+        reservations:
+          cpus: '0.10'
+          memory: 128M
 ```
 
-logspout can then be deployed as a global service in the swam with the following command
+logspout can then be deployed as a global service in the swarm with the following command
 
 ```bash
-docker stack deploy --compose-file <name of your compose file>
+docker stack deploy --compose-file <name of your compose file> STACK
 ```
 
 More information about services and their mode of deployment can be found here:
 https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/ 
 
+### TLS Settings
+logspout supports modification of the client TLS settings via environment variables described below:
+
+| Environment Variable  | Description |
+| :---                  |  :---       |
+| `LOGSPOUT_TLS_DISABLE_SYSTEM_ROOTS` | when set to `true` it disables loading the system trust store into the trust store of logspout |
+| `LOGSPOUT_TLS_CA_CERTS` | a comma seperated list of filesystem paths to pem encoded CA certificates that should be added to logsput's TLS trust store. Each pem file can contain more than one certificate |
+| `LOGSPOUT_TLS_CLIENT_CERT` | filesytem path to pem encoded x509 client certificate to load when TLS mutual authentication is desired |
+| `LOGSPOUT_TLS_CLIENT_KEY` | filesytem path to pem encoded client private key to load when TLS mutual authentication is desired |
+| `LOGSPOUT_TLS_HARDENING` | when set to `true` it enables stricter client TLS settings designed to mitigate some known TLS vulnerabilities |
+
+#### Example TLS settings
+The following settings cover some common use cases.
+When running docker, use the `-e` flag to supply environment variables
+
+**add your own CAs to the list of trusted authorities**
+```
+export LOGSPOUT_TLS_CA_CERTS="/opt/tls/ca/myRootCA1.pem,/opt/tls/ca/myRootCA2.pem"
+```
+
+**force logspout to ONLY trust your own CA**
+```
+export LOGSPOUT_TLS_DISABLE_SYSTEM_ROOTS=true
+export LOGSPOUT_TLS_CA_CERTS="/opt/tls/ca/myRootCA1.pem"
+```
+
+**configure client authentication**
+```
+export LOGSPOUT_TLS_CLIENT_CERT="/opt/tls/client/myClient.pem"
+export LOGSPOUT_TLS_CLIENT_KEY="/opt/tls/client/myClient-key.pem"
+```
+
+**highest possible security settings (paranoid mode)**
+```
+export LOGSPOUT_TLS_DISABLE_SYSTEM_ROOTS=true
+export LOGSPOUT_TLS_HARDENING=true
+export LOGSPOUT_TLS_CA_CERTS="/opt/tls/ca/myRootCA1.pem"
+export LOGSPOUT_TLS_CLIENT_CERT="/opt/tls/client/myClient.pem"
+export LOGSPOUT_TLS_CLIENT_KEY="/opt/tls/client/myClient-key.pem"
+```
+
 ## Modules
 
 The standard distribution of logspout comes with all modules defined in this repository. You can remove or add new modules with custom builds of logspout. In the `custom` dir, edit the `modules.go` file and do a `docker build`.
@@ -282,7 +324,7 @@ The standard distribution of logspout comes with all modules defined in this rep
 
 ### Third-party modules
 
- * [logspout-kafka](https://github.com/gettyimages/logspout-kafka)
+ * [logspout-kafka](https://github.com/dylanmei/logspout-kafka)
  * logspout-redis...
  * [logspout-logstash](https://github.com/looplab/logspout-logstash)
  * [logspout-redis-logstash](https://github.com/rtoma/logspout-redis-logstash)

VERSION

@@ -1 +1 @@
-v3.2.5
+v3.2.6

circle.yml

@@ -23,6 +23,8 @@ jobs:
           make -e test
       - run: |
           make -e test-tls
+      - run: |
+          make -e test-healthcheck
       - run: |
           make -e test-custom
       - run: |

healthcheck/healthcheck.go

@@ -0,0 +1,21 @@
+package healthcheck
+
+import (
+	"net/http"
+
+	"github.com/gliderlabs/logspout/router"
+	"github.com/gorilla/mux"
+)
+
+func init() {
+	router.HttpHandlers.Register(HealthCheck, "health")
+}
+
+// HealthCheck returns a http.Handler for the health check
+func HealthCheck() http.Handler {
+	r := mux.NewRouter()
+	r.HandleFunc("/health", func(w http.ResponseWriter, req *http.Request) {
+		w.Write([]byte("Healthy!\n"))
+	})
+	return r
+}

modules.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	_ "github.com/gliderlabs/logspout/healthcheck"
 	_ "github.com/gliderlabs/logspout/adapters/raw"
 	_ "github.com/gliderlabs/logspout/adapters/syslog"
 	_ "github.com/gliderlabs/logspout/adapters/multiline"

router/http.go

@@ -7,12 +7,14 @@ import (
 )
 
 func init() {
+	bindAddress := getopt("HTTP_BIND_ADDRESS", "0.0.0.0")
 	port := getopt("PORT", getopt("HTTP_PORT", "80"))
-	Jobs.Register(&httpService{port}, "http")
+	Jobs.Register(&httpService{bindAddress, port}, "http")
 }
 
 type httpService struct {
-	port string
+	bindAddress string
+	port        string
 }
 
 func (s *httpService) Name() string {
@@ -30,5 +32,5 @@ func (s *httpService) Setup() error {
 }
 
 func (s *httpService) Run() error {
-	return http.ListenAndServe(":"+s.port, nil)
+	return http.ListenAndServe(s.bindAddress+":"+s.port, nil)
 }