Merge branch 'markdown-new' of https://github.com/google/grr-doc into…

… markdown-new

docs/developing-grr/contributing.md

@@ -25,6 +25,17 @@ we recommend these as good starting points:
 
   - Add a new parser to parse a new filetype, e.g. if you have a
     different Anti-virus or HIDS log you want to parse.
+
+## Contributor License Agreement
+
+GRR is an opensource project released under the [Apache
+License](https://github.com/google/grr/blob/master/LICENSE) and you should feel
+free to use it in any way compatible with this.  However, in order to accept
+changes into the GRR mainline repository we must ask that keep a signed a
+[Google Contributor License Agreement](https://cla.developers.google.com/clas)
+on file.
+
+## Style
 
 The [Chromium](http://www.chromium.org/developers/contributing-code) and
 [Plaso](http://plaso.kiddaland.net/developer/style-guide) projects have
@@ -39,6 +50,8 @@ Note that despite what the guide says, we use two-space indentation, and
 MixedCase instead of lower\_underscore for function names since this is
 the internal standard. Two-space indentation also applies to CSS.
 
+## Setup
+
 We use the github [fork and pull review
 process](https://help.github.com/articles/using-pull-requests) to review
 all contributions.

docs/installing-grr-server/overview.md

@@ -1,3 +1,5 @@
+# Overview
+
 Depending on your use case, there are multiple ways of installing the
 GRR server components. Most users will want to
 [install a release deb](from-release-deb.md). The server deb includes
@@ -8,3 +10,29 @@ Alternatively, GRR can be [installed from PIP](from-released-pip.md).
 You can install also GRR from source as described
 [here](from-source.md). You should then be able to modify GRR code and build
 your own server/client installers.
+
+
+## GRR components
+
+GRR consists of a client and a few server components.
+
+Whenever GRR server is installed using one of the methods mentioned above, all the server components are installed. This is a simple way to setup smaller GRR server installations: each component will run as a separate server process on the same machine. However, when scaling GRR server to run on multiple machines, each component can exist on its own machine in the data center and run separately.
+
+GRR components are:
+
+#### Client
+
+The GRR client **is not a server component** but it comes bundled with GRR server. GRR client is deployed on corporate assets using the usual mechanism for software distribution and updates (e.g. SMS, apt). The client communicates with the front-end server using a HTTP POST requests. GRR client sends and receives GRR messages from the server. All communication with the front end servers is encrypted.
+
+#### Datastore
+The data store acts both as a central storage component for data, and as a communication mechanism for all GRR server components.
+
+#### Front End Servers
+The front end servers' main task is to decrypt POST requests from the client, un-bundle the contained messages and queue these on the data store. The front end also fetches any messages queued for the client and sends them to the client.
+
+#### Worker
+In order to remain scalable, the front end does not do any processing of data, preferring to offload processing to special worker components. The number of workers can be tuned in response to increased workload. Workers typically check queues in the data stores for responses from the client, process those and re-queue new requests for the clients (See Flows and Queues).
+
+#### Web UI
+GRR Web UI is the central application which enables the incident responder or forensic analyst to interact with the system. It allows for analysis tasks to be queued for the clients, and results of previous stored analysis to be examined. It also acts as an API endpoint: GRR API can be used for automation and integration with other systems.
+

docs/maintaining-and-tuning/approval-based-workflow.md

@@ -0,0 +1,49 @@
+# Approval-based workflow
+
+GRR has support for an approval-based access control system. To turn it on, set the *API.DefaultRouter* configuration option in the server configuration (see [API routers documentation](../maintaining-and-tuning/user-management/limiting-access-with-routers.md) for more details):
+
+``` yaml
+API.DefaultRouter: ApiCallRouterWithApprovalChecks
+```
+
+Approval-based workflow places certain restrictions on what users can do without getting an explicit approval from another user.
+
+## Actions that **don't require** an approval
+
+1. Searching for clients.
+1. Getting information about a client host (including the history).
+1. Looking at the list of hunts.
+1. Looking at hunt results, logs and other related data.
+1. Looking at cron jobs.
+
+
+## Actions that **do require** an approval
+
+1. Browsing client's Virtual File System.
+1. Inspecting client's flows.
+1. Starting new flows on a client.
+1. Starting a new hunt (**NOTE**: this is a special case - starting a hunt requires an approval from an [admin user](user-management/authentication.md)).
+1. Downloading files collected by a hunt.
+1. Starting a new cron job.
+
+## Requesting an approval
+
+Whenever you try to perform an action that requires an approval in the GRR web UI, you'll see a popup dialog similar to this one:
+
+![GRR approval dialog](../images/client-approval-dialog.png)
+
+You need to fill-in a comma-separated list of approvers. Each approver will get a notification about a pending approval request in their GRR web UI.
+
+You can also select *CC* option to send an email to a predefined email address. This helps if you have multiple possible approvers and they're all subscribed to the same mailing list. *CC* option will only work if you have a proper [Email Configuration](email-configuration) in your GRR server config.
+
+For every approval you also need to enter a reason you request one. This is done for auditing purposes. Also, when you access a client that you have an approval for, you'll see the reason displayed in GRR web UI's top left corner.
+
+## Granting an approval
+
+Whenever somebody requests an approval, you'll get a notification in the GRR web UI: the notification button in the top right corner will turn red and display a number of pending notifications.
+
+When you click on a *Please grant access to <...>* notification, you'll see an approval request review page similar to this one:
+
+![GRR approval review page](../images/client-approval-review-page.png)
+
+You can see the approval request reason on the review page and also some details about the object that the requestor is trying to access (a client, a hunt or a cron job). If you find the approval request justified, you click on the "Approve" button. The requestor will receive a notification then stating that the access was granted.

mkdocs.yml

@@ -57,7 +57,6 @@ pages:
   - Importing the NSRL: 'investigating-with-grr/importing-nsrl.md'
   - Glossary: 'investigating-with-grr/glossary.md'
 - Maintaining and tuning GRR deployment:
-  - Overview: 'maintaining-and-tuning/overview.md'
   - Changing GRR server configuration:
     - Configuration file organization: 'maintaining-and-tuning/configuration/file-organization.md'
     - Configuration contexts: 'maintaining-and-tuning/configuration/contexts.md'
@@ -71,7 +70,7 @@ pages:
     - Running GRR UI behind Apache web server: 'maintaining-and-tuning/user-management/running-behind-apache.md'
     - Limiting access to GRR UI/API with API routers: 'maintaining-and-tuning/user-management/limiting-access-with-routers.md'
   - Email configuration: 'maintaining-and-tuning/email-configuration.md'
-  - Approval-based auditing system: 'maintaining-and-tuning/approval-based-auditing.md'
+  - Approval-based access control: 'maintaining-and-tuning/approval-based-workflow.md'
   - Repacking GRR clients: 'maintaining-and-tuning/repacking-clients.md'
   - Low-level maintenance with grr_console: 'maintaining-and-tuning/low-level-maintenance-with-console.md'
   - Choosing GRR datastore: 'maintaining-and-tuning/choosing-datastore.md'