From ab58f4493c6b36cfe663af9c98bcba6ff71a299b Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Fri, 10 Aug 2018 18:50:48 -0700 Subject: [PATCH 01/11] adding draft for api auditing --- .../v2.x/en/faq/api-auditing/_index.md | 530 ++++++++++++++++++ 1 file changed, 530 insertions(+) create mode 100644 content/rancher/v2.x/en/faq/api-auditing/_index.md diff --git a/content/rancher/v2.x/en/faq/api-auditing/_index.md b/content/rancher/v2.x/en/faq/api-auditing/_index.md new file mode 100644 index 00000000000..4246bc13ad4 --- /dev/null +++ b/content/rancher/v2.x/en/faq/api-auditing/_index.md @@ -0,0 +1,530 @@ +--- +title: API Auditing +weight: 10000 +--- + +Rancher ships with API Auditing to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests to and responses from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. + +## Enabling API Auditing + +To enable API auditing, stop the Docker container that's running Rancher, and then restart it using the following command. This command includes parameters that turns on API auditing. For more information about usage for each switch related to API auditing, see [API Auditing Usage](#api-auditing-usage). + + +``` + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /root/var/log/auditlog:/var/log/auditlog \ + -e AUDIT_LEVEL=1 \ + -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ + -e AUDIT_LOG_MAXAGE=20 \ + -e AUDIT_LOG_MAXBACKUP=20 \ + -e AUDIT_LOG_MAXSIZE=100 \ + rancher/rancher:latest +``` + +## API Auditing Usage + +Each API request creates two entries for it in the audit log, one for reception and one for fulfillment: `RequestReceived` and `ResponseComplete`. Each status for a single request use the same `auditID` value. +The usage below defines rules about what the audit log should record and what data it should include: + + * AUDIT_LEVEL - 0 - disable audit log, 1 - log event metadata, 2 - log event metadata and request body, 3 - log event metadata, request body and response body + * AUDIT_LOG_PATH - Log path for Rancher Server API. Default path is /var/log/auditlog/rancher-api-audit.log, you can mount the log directory to host + * AUDIT_LOG_MAXAGE - Defined the maximum number of days to retain old audit log files, default is 10 days. + * AUDIT_LOG_MAXBACKUP - Defines the maximum number of audit log files to retain, default is 10 + * AUDIT_LOG_MAXSIZE - Defines the maximum size in megabytes of the audit log file before it gets rotated, default size is 100M + + + + +## Audit Log Samples + +By default, you can view the audit log at `/var/log/auditlog/rancher-api-audit.log` (although this path will change if you modify it). + +### Metadata Level +``` +{ + "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183", + "requestURI": "/v3/schemas", + "sourceIPs": [ + "::1" + ], + "user": { + "name": "user-f4tt2", + "group": [ + "system:authenticated" + ] + }, + "verb": "GET", + "stage": "RequestReceived", + "stageTimestamp": "2018-07-20 10:22:43 +0800" +} +``` +### Metadata and Request Body Level +``` +{ + "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb", + "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "sourceIPs": [ + "::1" + ], + "user": { + "name": "user-f4tt2", + "group": [ + "system:authenticated" + ] + }, + "verb": "PUT", + "stage": "RequestReceived", + "stageTimestamp": "2018-07-20 10:28:08 +0800", + "requestBody": { + "hostIPC": false, + "hostNetwork": false, + "hostPID": false, + "paused": false, + "annotations": {}, + "baseType": "workload", + "containers": [ + { + "allowPrivilegeEscalation": false, + "image": "nginx", + "imagePullPolicy": "Always", + "initContainer": false, + "name": "nginx", + "ports": [ + { + "containerPort": 80, + "dnsName": "nginx-nodeport", + "kind": "NodePort", + "name": "80tcp01", + "protocol": "TCP", + "sourcePort": 0, + "type": "/v3/project/schemas/containerPort" + } + ], + "privileged": false, + "readOnly": false, + "resources": { + "type": "/v3/project/schemas/resourceRequirements", + "requests": {}, + "limits": {} + }, + "restartCount": 0, + "runAsNonRoot": false, + "stdin": true, + "stdinOnce": false, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "tty": true, + "type": "/v3/project/schemas/container", + "environmentFrom": [], + "capAdd": [], + "capDrop": [], + "livenessProbe": null, + "volumeMounts": [] + } + ], + "created": "2018-07-18T07:34:16Z", + "createdTS": 1531899256000, + "creatorId": null, + "deploymentConfig": { + "maxSurge": 1, + "maxUnavailable": 0, + "minReadySeconds": 0, + "progressDeadlineSeconds": 600, + "revisionHistoryLimit": 10, + "strategy": "RollingUpdate" + }, + "deploymentStatus": { + "availableReplicas": 1, + "conditions": [ + { + "lastTransitionTime": "2018-07-18T07:34:38Z", + "lastTransitionTimeTS": 1531899278000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2018-07-18T07:34:16Z", + "lastTransitionTimeTS": 1531899256000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.", + "reason": "NewReplicaSetAvailable", + "status": "True", + "type": "Progressing" + } + ], + "observedGeneration": 2, + "readyReplicas": 1, + "replicas": 1, + "type": "/v3/project/schemas/deploymentStatus", + "unavailableReplicas": 0, + "updatedReplicas": 1 + }, + "dnsPolicy": "ClusterFirst", + "id": "deployment:default:nginx", + "labels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "name": "nginx", + "namespaceId": "default", + "projectId": "c-bcz5t:p-fdr4s", + "publicEndpoints": [ + { + "addresses": [ + "10.64.3.58" + ], + "allNodes": true, + "ingressId": null, + "nodeId": null, + "podId": null, + "port": 30917, + "protocol": "TCP", + "serviceId": "default:nginx-nodeport", + "type": "publicEndpoint" + } + ], + "restartPolicy": "Always", + "scale": 1, + "schedulerName": "default-scheduler", + "selector": { + "matchLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "type": "/v3/project/schemas/labelSelector" + }, + "state": "active", + "terminationGracePeriodSeconds": 30, + "transitioning": "no", + "transitioningMessage": "", + "type": "deployment", + "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd", + "workloadAnnotations": { + "deployment.kubernetes.io/revision": "1", + "field.cattle.io/creatorId": "user-f4tt2" + }, + "workloadLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "scheduling": { + "node": {} + }, + "description": "my description", + "volumes": [] + } +} +``` +### Metadata, Request Body and Response Body Level + +#### Request +``` +{ + "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af", + "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "sourceIPs": [ + "::1" + ], + "user": { + "name": "user-f4tt2", + "group": [ + "system:authenticated" + ] + }, + "verb": "PUT", + "stage": "RequestReceived", + "stageTimestamp": "2018-07-20 10:33:06 +0800", + "requestBody": { + "hostIPC": false, + "hostNetwork": false, + "hostPID": false, + "paused": false, + "annotations": {}, + "baseType": "workload", + "containers": [ + { + "allowPrivilegeEscalation": false, + "image": "nginx", + "imagePullPolicy": "Always", + "initContainer": false, + "name": "nginx", + "ports": [ + { + "containerPort": 80, + "dnsName": "nginx-nodeport", + "kind": "NodePort", + "name": "80tcp01", + "protocol": "TCP", + "sourcePort": 0, + "type": "/v3/project/schemas/containerPort" + } + ], + "privileged": false, + "readOnly": false, + "resources": { + "type": "/v3/project/schemas/resourceRequirements", + "requests": {}, + "limits": {} + }, + "restartCount": 0, + "runAsNonRoot": false, + "stdin": true, + "stdinOnce": false, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "tty": true, + "type": "/v3/project/schemas/container", + "environmentFrom": [], + "capAdd": [], + "capDrop": [], + "livenessProbe": null, + "volumeMounts": [] + } + ], + "created": "2018-07-18T07:34:16Z", + "createdTS": 1531899256000, + "creatorId": null, + "deploymentConfig": { + "maxSurge": 1, + "maxUnavailable": 0, + "minReadySeconds": 0, + "progressDeadlineSeconds": 600, + "revisionHistoryLimit": 10, + "strategy": "RollingUpdate" + }, + "deploymentStatus": { + "availableReplicas": 1, + "conditions": [ + { + "lastTransitionTime": "2018-07-18T07:34:38Z", + "lastTransitionTimeTS": 1531899278000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2018-07-18T07:34:16Z", + "lastTransitionTimeTS": 1531899256000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.", + "reason": "NewReplicaSetAvailable", + "status": "True", + "type": "Progressing" + } + ], + "observedGeneration": 2, + "readyReplicas": 1, + "replicas": 1, + "type": "/v3/project/schemas/deploymentStatus", + "unavailableReplicas": 0, + "updatedReplicas": 1 + }, + "dnsPolicy": "ClusterFirst", + "id": "deployment:default:nginx", + "labels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "name": "nginx", + "namespaceId": "default", + "projectId": "c-bcz5t:p-fdr4s", + "publicEndpoints": [ + { + "addresses": [ + "10.64.3.58" + ], + "allNodes": true, + "ingressId": null, + "nodeId": null, + "podId": null, + "port": 30917, + "protocol": "TCP", + "serviceId": "default:nginx-nodeport", + "type": "publicEndpoint" + } + ], + "restartPolicy": "Always", + "scale": 1, + "schedulerName": "default-scheduler", + "selector": { + "matchLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "type": "/v3/project/schemas/labelSelector" + }, + "state": "active", + "terminationGracePeriodSeconds": 30, + "transitioning": "no", + "transitioningMessage": "", + "type": "deployment", + "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd", + "workloadAnnotations": { + "deployment.kubernetes.io/revision": "1", + "field.cattle.io/creatorId": "user-f4tt2" + }, + "workloadLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "scheduling": { + "node": {} + }, + "description": "my decript", + "volumes": [] + } +} +``` + +#### Response +``` +{ + "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af", + "responseStatus": "200", + "stage": "ResponseComplete", + "stageTimestamp": "2018-07-20 10:33:06 +0800", + "responseBody": { + "actionLinks": { + "pause": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=pause", + "resume": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=resume", + "rollback": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=rollback" + }, + "annotations": {}, + "baseType": "workload", + "containers": [ + { + "allowPrivilegeEscalation": false, + "image": "nginx", + "imagePullPolicy": "Always", + "initContainer": false, + "name": "nginx", + "ports": [ + { + "containerPort": 80, + "dnsName": "nginx-nodeport", + "kind": "NodePort", + "name": "80tcp01", + "protocol": "TCP", + "sourcePort": 0, + "type": "/v3/project/schemas/containerPort" + } + ], + "privileged": false, + "readOnly": false, + "resources": { + "type": "/v3/project/schemas/resourceRequirements" + }, + "restartCount": 0, + "runAsNonRoot": false, + "stdin": true, + "stdinOnce": false, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "tty": true, + "type": "/v3/project/schemas/container" + } + ], + "created": "2018-07-18T07:34:16Z", + "createdTS": 1531899256000, + "creatorId": null, + "deploymentConfig": { + "maxSurge": 1, + "maxUnavailable": 0, + "minReadySeconds": 0, + "progressDeadlineSeconds": 600, + "revisionHistoryLimit": 10, + "strategy": "RollingUpdate" + }, + "deploymentStatus": { + "availableReplicas": 1, + "conditions": [ + { + "lastTransitionTime": "2018-07-18T07:34:38Z", + "lastTransitionTimeTS": 1531899278000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2018-07-18T07:34:16Z", + "lastTransitionTimeTS": 1531899256000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.", + "reason": "NewReplicaSetAvailable", + "status": "True", + "type": "Progressing" + } + ], + "observedGeneration": 2, + "readyReplicas": 1, + "replicas": 1, + "type": "/v3/project/schemas/deploymentStatus", + "unavailableReplicas": 0, + "updatedReplicas": 1 + }, + "dnsPolicy": "ClusterFirst", + "hostIPC": false, + "hostNetwork": false, + "hostPID": false, + "id": "deployment:default:nginx", + "labels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "links": { + "remove": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "revisions": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/revisions", + "self": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "update": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "yaml": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/yaml" + }, + "name": "nginx", + "namespaceId": "default", + "paused": false, + "projectId": "c-bcz5t:p-fdr4s", + "publicEndpoints": [ + { + "addresses": [ + "10.64.3.58" + ], + "allNodes": true, + "ingressId": null, + "nodeId": null, + "podId": null, + "port": 30917, + "protocol": "TCP", + "serviceId": "default:nginx-nodeport" + } + ], + "restartPolicy": "Always", + "scale": 1, + "schedulerName": "default-scheduler", + "selector": { + "matchLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "type": "/v3/project/schemas/labelSelector" + }, + "state": "active", + "terminationGracePeriodSeconds": 30, + "transitioning": "no", + "transitioningMessage": "", + "type": "deployment", + "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd", + "workloadAnnotations": { + "deployment.kubernetes.io/revision": "1", + "field.cattle.io/creatorId": "user-f4tt2" + }, + "workloadLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + } + } +} +``` \ No newline at end of file From 68eaab9f19c23e82a46347f69a11a4404feb88ac Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Mon, 13 Aug 2018 13:04:35 -0700 Subject: [PATCH 02/11] adding more content. --- .../v2.x/en/faq/api-auditing/_index.md | 36 +++++++++++++------ 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/content/rancher/v2.x/en/faq/api-auditing/_index.md b/content/rancher/v2.x/en/faq/api-auditing/_index.md index 4246bc13ad4..4b719a31f4e 100644 --- a/content/rancher/v2.x/en/faq/api-auditing/_index.md +++ b/content/rancher/v2.x/en/faq/api-auditing/_index.md @@ -3,13 +3,13 @@ title: API Auditing weight: 10000 --- -Rancher ships with API Auditing to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests to and responses from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. +Rancher ships with API Auditing to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. ## Enabling API Auditing To enable API auditing, stop the Docker container that's running Rancher, and then restart it using the following command. This command includes parameters that turns on API auditing. For more information about usage for each switch related to API auditing, see [API Auditing Usage](#api-auditing-usage). - + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -27,20 +27,34 @@ To enable API auditing, stop the Docker container that's running Rancher, and th Each API request creates two entries for it in the audit log, one for reception and one for fulfillment: `RequestReceived` and `ResponseComplete`. Each status for a single request use the same `auditID` value. The usage below defines rules about what the audit log should record and what data it should include: - * AUDIT_LEVEL - 0 - disable audit log, 1 - log event metadata, 2 - log event metadata and request body, 3 - log event metadata, request body and response body - * AUDIT_LOG_PATH - Log path for Rancher Server API. Default path is /var/log/auditlog/rancher-api-audit.log, you can mount the log directory to host - * AUDIT_LOG_MAXAGE - Defined the maximum number of days to retain old audit log files, default is 10 days. - * AUDIT_LOG_MAXBACKUP - Defines the maximum number of audit log files to retain, default is 10 - * AUDIT_LOG_MAXSIZE - Defines the maximum size in megabytes of the audit log file before it gets rotated, default size is 100M - + +Parameter | Description | +---------|----------| + `AUDIT_LEVEL` | `0` - Disable audit log.
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. | + `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. | + `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | + `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. + `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. +## Viewing API Audit Logs + +By default, you can view your audit logs on any of your cluster nodes at `root/var/log/auditlog/rancher-api-audit.log` using your favorite text editor. For example: + +``` +less /var/log/auditlog/rancher-api-audit.log +``` + +If you changed the `AUDIT_LOG_PATH` parameter, look in that location for `rancher-api-audit.log` instead. ## Audit Log Samples -By default, you can view the audit log at `/var/log/auditlog/rancher-api-audit.log` (although this path will change if you modify it). +After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction. ### Metadata Level + +If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every API request and response, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. + ``` { "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183", @@ -59,7 +73,9 @@ By default, you can view the audit log at `/var/log/auditlog/rancher-api-audit.l "stageTimestamp": "2018-07-20 10:22:43 +0800" } ``` + ### Metadata and Request Body Level + ``` { "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb", @@ -218,7 +234,7 @@ By default, you can view the audit log at `/var/log/auditlog/rancher-api-audit.l } } ``` -### Metadata, Request Body and Response Body Level +### Metadata, Request Body, and Response Body Level #### Request ``` From dba3bae1ed6cee41a83aee11da0b0af8c0283465 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Mon, 13 Aug 2018 13:45:39 -0700 Subject: [PATCH 03/11] adding content about what's included in each logging level. --- .../v2.x/en/faq/api-auditing/_index.md | 32 +++++++++++++++---- 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/content/rancher/v2.x/en/faq/api-auditing/_index.md b/content/rancher/v2.x/en/faq/api-auditing/_index.md index 4b719a31f4e..8877fa0ddba 100644 --- a/content/rancher/v2.x/en/faq/api-auditing/_index.md +++ b/content/rancher/v2.x/en/faq/api-auditing/_index.md @@ -24,7 +24,8 @@ To enable API auditing, stop the Docker container that's running Rancher, and th ## API Auditing Usage -Each API request creates two entries for it in the audit log, one for reception and one for fulfillment: `RequestReceived` and `ResponseComplete`. Each status for a single request use the same `auditID` value. +Each API transaction creates two entries for it in the audit log, one for requests and one for response: `RequestReceived` and `ResponseComplete`. Each log transaction for a request/response pair uses the same `auditID` value. + The usage below defines rules about what the audit log should record and what data it should include: @@ -53,9 +54,9 @@ After you enable auditing, each API request or response is logged by Rancher in ### Metadata Level -If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every API request and response, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. +If you set your `AUDIT_LEVEL` to `1` or higher, Rancher logs the metadata header for every API request and response, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. -``` +```json { "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183", "requestURI": "/v3/schemas", @@ -76,7 +77,14 @@ If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every ### Metadata and Request Body Level -``` +If you set your `AUDIT_LEVEL` to `2` or higher, Rancher logs: + +- The metadata header and body for every API request. +- The metadata header only for every API response. + +The code sample below depicts an API request, with both its metadata header and body. + +```json { "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb", "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", @@ -236,8 +244,16 @@ If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every ``` ### Metadata, Request Body, and Response Body Level +If you set your `AUDIT_LEVEL` to `3` or higher, Rancher logs: + +- The metadata header and body for every API request. +- The metadata header and body for every API response. + #### Request -``` + +The code sample below depicts an API request, with both its metadata header and body. + +```json { "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af", "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", @@ -397,7 +413,11 @@ If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every ``` #### Response -``` + +The code sample below depicts an API response, with both its metadata header and body. + + +```json { "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af", "responseStatus": "200", From 3af363e4739752d2d3cccfa56f40cabf48fc6ff3 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 15 Aug 2018 17:31:00 -0700 Subject: [PATCH 04/11] moving to install section --- .../api-auditing/_index.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) rename content/rancher/v2.x/en/{faq => installation}/api-auditing/_index.md (100%) diff --git a/content/rancher/v2.x/en/faq/api-auditing/_index.md b/content/rancher/v2.x/en/installation/api-auditing/_index.md similarity index 100% rename from content/rancher/v2.x/en/faq/api-auditing/_index.md rename to content/rancher/v2.x/en/installation/api-auditing/_index.md index 8877fa0ddba..69f54ff47d3 100644 --- a/content/rancher/v2.x/en/faq/api-auditing/_index.md +++ b/content/rancher/v2.x/en/installation/api-auditing/_index.md @@ -5,6 +5,22 @@ weight: 10000 Rancher ships with API Auditing to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. +## API Auditing Usage + +Each API transaction creates two entries for it in the audit log, one for requests and one for response: `RequestReceived` and `ResponseComplete`. Each log transaction for a request/response pair uses the same `auditID` value. + +The usage below defines rules about what the audit log should record and what data it should include: + + +Parameter | Description | +---------|----------| + `AUDIT_LEVEL` | `0` - Disable audit log.
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. | + `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. | + `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | + `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. + `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. + + ## Enabling API Auditing To enable API auditing, stop the Docker container that's running Rancher, and then restart it using the following command. This command includes parameters that turns on API auditing. For more information about usage for each switch related to API auditing, see [API Auditing Usage](#api-auditing-usage). @@ -22,22 +38,6 @@ To enable API auditing, stop the Docker container that's running Rancher, and th rancher/rancher:latest ``` -## API Auditing Usage - -Each API transaction creates two entries for it in the audit log, one for requests and one for response: `RequestReceived` and `ResponseComplete`. Each log transaction for a request/response pair uses the same `auditID` value. - -The usage below defines rules about what the audit log should record and what data it should include: - - -Parameter | Description | ----------|----------| - `AUDIT_LEVEL` | `0` - Disable audit log.
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. | - `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. | - `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | - `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. - `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. - - ## Viewing API Audit Logs By default, you can view your audit logs on any of your cluster nodes at `root/var/log/auditlog/rancher-api-audit.log` using your favorite text editor. For example: From 712f2848934095730842ac4baa5cb50cbac94679 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 15 Aug 2018 18:41:19 -0700 Subject: [PATCH 05/11] adding content to RKE --- .../en/installation/api-auditing/_index.md | 2 + .../en/installation/single-node/_index.md | 10 ++++ .../add-ons/api-auditing/_index.md | 47 +++++++++++++++++++ 3 files changed, 59 insertions(+) create mode 100644 content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md diff --git a/content/rancher/v2.x/en/installation/api-auditing/_index.md b/content/rancher/v2.x/en/installation/api-auditing/_index.md index 69f54ff47d3..baace9ceb47 100644 --- a/content/rancher/v2.x/en/installation/api-auditing/_index.md +++ b/content/rancher/v2.x/en/installation/api-auditing/_index.md @@ -5,6 +5,8 @@ weight: 10000 Rancher ships with API Auditing to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. +You can enable API Auditing during Rancher installation or upgrade. + ## API Auditing Usage Each API transaction creates two entries for it in the audit log, one for requests and one for response: `RequestReceived` and `ResponseComplete`. Each log transaction for a request/response pair uses the same `auditID` value. diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index dbad2d3808e..23aacfa6808 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -68,6 +68,16 @@ Choose from the following options: - [Option D—Bring Your Own Certificate: Private CA Root Certificate CA](#option-d-bring-your-own-certificate-private-ca-root-certificate) - [Option E—Let's Encrypt Certificate](#option-e-let-s-encrypt-certificate) +>**Note:** When entering the command to install Rancher using any of the options below, you can declare additional flags to enable [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing), which records all interactions with the Rancher API. If you want to enable API Auditing, append the following flags to your install command: +> +>``` +-e AUDIT_LEVEL=1 \ +-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ +-e AUDIT_LOG_MAXAGE=20 \ +-e AUDIT_LOG_MAXBACKUP=20 \ +-e AUDIT_LOG_MAXSIZE=100 \ +``` + ### Option A—Default Self-Signed Certificate If you install Rancher without using your own certificate, Rancher generates a self-signed certificate that's used for encryption. If you're satisfied with this certificate, there's no need to obtain your own. diff --git a/content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md b/content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md new file mode 100644 index 00000000000..6b4e72ff36b --- /dev/null +++ b/content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md @@ -0,0 +1,47 @@ +--- +title: API Auditing +weight: 10000 +--- + +If you're using RKE to install Rancher, you can use directives to enable API Auditing for your Rancher install. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. + +## In-line Arguments + +Enable API Auditing using RKE by adding arguments to your Rancher container. + +To enable API auditing: + +- Add API Auditing arguments (`args`) to your Rancher container. +- Declare a `mountPath` in the `volumeMounts` directive of the container. +- Declare a `path` in the `volumes` directive. + +For more information about each argument, its syntax, and how to view API Audit logs, see [Rancher v2.0 Documentation: API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing). + +```yaml +... +containers: + - image: rancher/rancher:latest + imagePullPolicy: Always + name: cattle-server + args: ["--audit-log-path", "/var/log/auditlog/rancher-api-audit.log", "--audit-log-maxbackup", "5", "--audit-log-maxsize", "50", "--audit-level", "2"] + ports: + - containerPort: 80 + protocol: TCP + - containerPort: 443 + protocol: TCP + volumeMounts: + - mountPath: /etc/rancher/ssl + name: cattle-keys-volume + readOnly: true + - mountPath: /var/log/auditlog + name: audit-log-dir + volumes: + - name: cattle-keys-volume + secret: + defaultMode: 420 + secretName: cattle-keys-server + - name: audit-log-dir + hostPath: + path: /var/log/rancher/auditlog + type: Directory +``` From df3d410e7f452f0f8a306b83a096390fcbdb71fe Mon Sep 17 00:00:00 2001 From: MBishop17 Date: Fri, 17 Aug 2018 18:33:45 -0700 Subject: [PATCH 06/11] added notes to install procedure about setting up API auditing --- .../en/installation/ha/rke-add-on/layer-4-lb/_index.md | 2 ++ .../en/installation/ha/rke-add-on/layer-7-lb/_index.md | 3 +++ .../single-node-install-external-lb/_index.md | 10 ++++++++++ 3 files changed, 15 insertions(+) diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md index 581fa1b6f21..d253f14cbc9 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md @@ -230,6 +230,8 @@ RKE uses a `.yml` config file to install and configure your Kubernetes cluster. - [Template for self-signed certificate
`3-node-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-certificate-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/d8ca0805a3958552e84fdf5d743859097ae81e0b/rke-templates/3-node-certificate-recognizedca.yml) + >**Note:** When setting up your RKE config file, you can declare additional flags to enable API Auditing, which records all interactions with the Rancher API. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + 2. Rename the file to `rancher-cluster.yml`. ## 6. Configure Nodes diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md index a000c8089ea..d717805103e 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md @@ -179,6 +179,9 @@ RKE uses a YAML config file to install and configure your Kubernetes cluster. Th - [Template for self-signed certificate
`3-node-externalssl-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/58e695b51096b1f404188379cea6f6a35aea9e4c/rke-templates/3-node-externalssl-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-externalssl-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/7f60dc3afe1b45287ac36ba6bde6f7c6e35c11fe/rke-templates/3-node-externalssl-recognizedca.yml) + >**Note:** When setting up your RKE config file, you can declare additional flags to enable API Auditing, which records all interactions with the Rancher API. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + + 2. Rename the file to `rancher-cluster.yml`. ## 6. Configure Nodes diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index 0340095d70b..27be3372e95 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -70,6 +70,16 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher - [Option A-Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed) - [Option B-Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca) +>**Note:** When entering the command to install Rancher using any of the options below, you can declare additional flags to enable [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing), which records all interactions with the Rancher API. If you want to enable API Auditing, append the following flags to your install command: +> +>``` +-e AUDIT_LEVEL=1 \ +-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ +-e AUDIT_LOG_MAXAGE=20 \ +-e AUDIT_LOG_MAXBACKUP=20 \ +-e AUDIT_LOG_MAXSIZE=100 \ +``` + ### Option A-Bring Your Own Certificate: Self-Signed If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the docker command to deploy Rancher, pointing it toward your certificate. From 54313f1c0cc76e6708c8a472ad2391ed67ae0bb8 Mon Sep 17 00:00:00 2001 From: MBishop17 Date: Fri, 17 Aug 2018 18:42:36 -0700 Subject: [PATCH 07/11] added note to upgrade procedures about enabling api auditing --- .../en/upgrades/upgrades/ha-server-upgrade/_index.md | 2 ++ .../en/upgrades/upgrades/single-node-upgrade/_index.md | 10 ++++++++++ 2 files changed, 12 insertions(+) diff --git a/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md index 0e699a7a9df..3ad286e039c 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md @@ -17,6 +17,8 @@ To upgrade Rancher 2.x running in a high availability configuration, run an upgr 1. Change directory to the location of the RKE binary. Your `rancher-cluster.yml` file must reside in the same directory. + >**Note:** Before upgrade, you can configure `rancher-cluster.yml` to enable API Auditing, which records all interactions with the Rancher API. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + 1. Enter the following command. Replace `` with any name that you want to use for the snapshot (e.g. `upgrade.db`). ``` diff --git a/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md index 6247147afa8..3fe912c750e 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md @@ -55,6 +55,16 @@ docker pull rancher/rancher:latest docker run -d --volumes-from rancher-data --restart=unless-stopped \ -p 80:80 -p 443:443 rancher/rancher:latest ``` + >**Note:** When entering the command to upgrade Rancher, you can declare additional flags to enable [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing), which records all interactions with the Rancher API. If you want to enable API Auditing, append the following flags to your upgrade command: +> +>``` +-e AUDIT_LEVEL=1 \ +-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ +-e AUDIT_LOG_MAXAGE=20 \ +-e AUDIT_LOG_MAXBACKUP=20 \ +-e AUDIT_LOG_MAXSIZE=100 \ +``` + >**Note:** _Do not_ stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. >
>
From 80fa6664d63b7e6fa4a561f7b70a02827650eb6f Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Fri, 17 Aug 2018 19:24:15 -0700 Subject: [PATCH 08/11] simplified note text --- .../v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md | 4 +++- .../v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md | 4 +++- content/rancher/v2.x/en/installation/single-node/_index.md | 3 ++- .../single-node/single-node-install-external-lb/_index.md | 3 ++- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md index d253f14cbc9..bf733712064 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md @@ -230,7 +230,9 @@ RKE uses a `.yml` config file to install and configure your Kubernetes cluster. - [Template for self-signed certificate
`3-node-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-certificate-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/d8ca0805a3958552e84fdf5d743859097ae81e0b/rke-templates/3-node-certificate-recognizedca.yml) - >**Note:** When setting up your RKE config file, you can declare additional flags to enable API Auditing, which records all interactions with the Rancher API. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + >**Want records of all transactions with the Rancher API?:** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). 2. Rename the file to `rancher-cluster.yml`. diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md index d717805103e..35c362aebfa 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md @@ -179,7 +179,9 @@ RKE uses a YAML config file to install and configure your Kubernetes cluster. Th - [Template for self-signed certificate
`3-node-externalssl-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/58e695b51096b1f404188379cea6f6a35aea9e4c/rke-templates/3-node-externalssl-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-externalssl-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/7f60dc3afe1b45287ac36ba6bde6f7c6e35c11fe/rke-templates/3-node-externalssl-recognizedca.yml) - >**Note:** When setting up your RKE config file, you can declare additional flags to enable API Auditing, which records all interactions with the Rancher API. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + >**Want records of all transactions with the Rancher API?:** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). 2. Rename the file to `rancher-cluster.yml`. diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index 23aacfa6808..7536fa36d30 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -68,8 +68,9 @@ Choose from the following options: - [Option D—Bring Your Own Certificate: Private CA Root Certificate CA](#option-d-bring-your-own-certificate-private-ca-root-certificate) - [Option E—Let's Encrypt Certificate](#option-e-let-s-encrypt-certificate) ->**Note:** When entering the command to install Rancher using any of the options below, you can declare additional flags to enable [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing), which records all interactions with the Rancher API. If you want to enable API Auditing, append the following flags to your install command: +>**Want records of all transactions with the Rancher API?:** > +>Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. >``` -e AUDIT_LEVEL=1 \ -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index 27be3372e95..a6e8d69a98c 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -70,8 +70,9 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher - [Option A-Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed) - [Option B-Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca) ->**Note:** When entering the command to install Rancher using any of the options below, you can declare additional flags to enable [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing), which records all interactions with the Rancher API. If you want to enable API Auditing, append the following flags to your install command: +>**Want records of all transactions with the Rancher API?:** > +>Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. >``` -e AUDIT_LEVEL=1 \ -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ From 482af982a14db8214358652a4e1d0be2d470b5de Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Fri, 17 Aug 2018 19:41:14 -0700 Subject: [PATCH 09/11] improved text for upgrade --- .../ha/rke-add-on/layer-4-lb/_index.md | 2 +- .../ha/rke-add-on/layer-7-lb/_index.md | 2 +- .../en/installation/single-node/_index.md | 2 +- .../single-node-install-external-lb/_index.md | 2 +- .../upgrades/ha-server-upgrade/_index.md | 4 +++- .../upgrades/single-node-upgrade/_index.md | 20 ++++++++++--------- 6 files changed, 18 insertions(+), 14 deletions(-) diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md index bf733712064..94a8ec04c51 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md @@ -230,7 +230,7 @@ RKE uses a `.yml` config file to install and configure your Kubernetes cluster. - [Template for self-signed certificate
`3-node-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-certificate-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/d8ca0805a3958552e84fdf5d743859097ae81e0b/rke-templates/3-node-certificate-recognizedca.yml) - >**Want records of all transactions with the Rancher API?:** + >**Want records of all transactions with the Rancher API?** > >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md index 35c362aebfa..ea91ca4e2f7 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md @@ -179,7 +179,7 @@ RKE uses a YAML config file to install and configure your Kubernetes cluster. Th - [Template for self-signed certificate
`3-node-externalssl-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/58e695b51096b1f404188379cea6f6a35aea9e4c/rke-templates/3-node-externalssl-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-externalssl-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/7f60dc3afe1b45287ac36ba6bde6f7c6e35c11fe/rke-templates/3-node-externalssl-recognizedca.yml) - >**Want records of all transactions with the Rancher API?:** + >**Want records of all transactions with the Rancher API?** > >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index 7536fa36d30..c1d80c5ed67 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -68,7 +68,7 @@ Choose from the following options: - [Option D—Bring Your Own Certificate: Private CA Root Certificate CA](#option-d-bring-your-own-certificate-private-ca-root-certificate) - [Option E—Let's Encrypt Certificate](#option-e-let-s-encrypt-certificate) ->**Want records of all transactions with the Rancher API?:** +>**Want records of all transactions with the Rancher API?** > >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. >``` diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index a6e8d69a98c..b58c10ed707 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -70,7 +70,7 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher - [Option A-Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed) - [Option B-Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca) ->**Want records of all transactions with the Rancher API?:** +>**Want records of all transactions with the Rancher API?** > >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. >``` diff --git a/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md index 3ad286e039c..416ada0d3a3 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md @@ -17,7 +17,9 @@ To upgrade Rancher 2.x running in a high availability configuration, run an upgr 1. Change directory to the location of the RKE binary. Your `rancher-cluster.yml` file must reside in the same directory. - >**Note:** Before upgrade, you can configure `rancher-cluster.yml` to enable API Auditing, which records all interactions with the Rancher API. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + >**Want records of all transactions with the Rancher API?** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file (`rancher-cluster.yml`). For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). 1. Enter the following command. Replace `` with any name that you want to use for the snapshot (e.g. `upgrade.db`). diff --git a/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md index 3fe912c750e..80d9f0c4db2 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md @@ -55,15 +55,17 @@ docker pull rancher/rancher:latest docker run -d --volumes-from rancher-data --restart=unless-stopped \ -p 80:80 -p 443:443 rancher/rancher:latest ``` - >**Note:** When entering the command to upgrade Rancher, you can declare additional flags to enable [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing), which records all interactions with the Rancher API. If you want to enable API Auditing, append the following flags to your upgrade command: -> ->``` --e AUDIT_LEVEL=1 \ --e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ --e AUDIT_LOG_MAXAGE=20 \ --e AUDIT_LOG_MAXBACKUP=20 \ --e AUDIT_LOG_MAXSIZE=100 \ -``` + + >**Want records of all transactions with the Rancher API?** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your upgrade command. + >``` + -e AUDIT_LEVEL=1 \ + -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ + -e AUDIT_LOG_MAXAGE=20 \ + -e AUDIT_LOG_MAXBACKUP=20 \ + -e AUDIT_LOG_MAXSIZE=100 \ + ``` >**Note:** _Do not_ stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. >
From 4ac8967318ffaea143f559667639face336ec48f Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Mon, 20 Aug 2018 13:23:20 -0700 Subject: [PATCH 10/11] adding Michelia's corrections --- .../v2.x/en/installation/api-auditing/_index.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/content/rancher/v2.x/en/installation/api-auditing/_index.md b/content/rancher/v2.x/en/installation/api-auditing/_index.md index baace9ceb47..01262681cdf 100644 --- a/content/rancher/v2.x/en/installation/api-auditing/_index.md +++ b/content/rancher/v2.x/en/installation/api-auditing/_index.md @@ -9,15 +9,13 @@ You can enable API Auditing during Rancher installation or upgrade. ## API Auditing Usage -Each API transaction creates two entries for it in the audit log, one for requests and one for response: `RequestReceived` and `ResponseComplete`. Each log transaction for a request/response pair uses the same `auditID` value. - The usage below defines rules about what the audit log should record and what data it should include: Parameter | Description | ---------|----------| - `AUDIT_LEVEL` | `0` - Disable audit log.
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. | - `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. | + `AUDIT_LEVEL` | `0` - Disable audit log (default setting).
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value. | + `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host.

Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`
| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. @@ -56,7 +54,7 @@ After you enable auditing, each API request or response is logged by Rancher in ### Metadata Level -If you set your `AUDIT_LEVEL` to `1` or higher, Rancher logs the metadata header for every API request and response, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. +If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every API request and response, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. ```json { @@ -79,10 +77,10 @@ If you set your `AUDIT_LEVEL` to `1` or higher, Rancher logs the metadata header ### Metadata and Request Body Level -If you set your `AUDIT_LEVEL` to `2` or higher, Rancher logs: +If you set your `AUDIT_LEVEL` to `2`, Rancher logs: - The metadata header and body for every API request. -- The metadata header only for every API response. +- Only the metadata header for every API response. The code sample below depicts an API request, with both its metadata header and body. @@ -246,7 +244,7 @@ The code sample below depicts an API request, with both its metadata header and ``` ### Metadata, Request Body, and Response Body Level -If you set your `AUDIT_LEVEL` to `3` or higher, Rancher logs: +If you set your `AUDIT_LEVEL` to `3`, Rancher logs: - The metadata header and body for every API request. - The metadata header and body for every API response. From fca02fb91a761a89c78917e5b2f739b4458ac20c Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 22 Aug 2018 12:03:29 -0700 Subject: [PATCH 11/11] Added Michaela's feedback, added table --- .../en/installation/api-auditing/_index.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/content/rancher/v2.x/en/installation/api-auditing/_index.md b/content/rancher/v2.x/en/installation/api-auditing/_index.md index 01262681cdf..e20747d0897 100644 --- a/content/rancher/v2.x/en/installation/api-auditing/_index.md +++ b/content/rancher/v2.x/en/installation/api-auditing/_index.md @@ -14,12 +14,23 @@ The usage below defines rules about what the audit log should record and what da Parameter | Description | ---------|----------| - `AUDIT_LEVEL` | `0` - Disable audit log (default setting).
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value. | + `AUDIT_LEVEL` | `0` - Disable audit log (default setting).
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value.

See [Audit Level Logging](#audit-level-logging) for a table that displays what each setting logs. | `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host.

Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`
| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. +
+#### Audit Level Logging + +The following table displays what parts of API transactions are logged for each [`AUDIT_LEVEL`](#audit-level) setting. + +| `AUDIT_LEVEL` Setting | Request Header | Request Body | Response Header | Response Header | +| --------------------- | ------------------ | ------------ | ------------------- | ------------------- | +| `0` | | | | | +| `1` | ✓ | | | | +| `2` | ✓ | ✓ | | | +| `3` | ✓ | ✓ | ✓ | ✓ | ## Enabling API Auditing @@ -54,7 +65,7 @@ After you enable auditing, each API request or response is logged by Rancher in ### Metadata Level -If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every API request and response, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. +If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every API request, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc. ```json { @@ -77,10 +88,8 @@ If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata header for every ### Metadata and Request Body Level -If you set your `AUDIT_LEVEL` to `2`, Rancher logs: +If you set your `AUDIT_LEVEL` to `2`, Rancher logs the metadata header and body for every API request. -- The metadata header and body for every API request. -- Only the metadata header for every API response. The code sample below depicts an API request, with both its metadata header and body.