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

… markdown-new

docs/deploying-grr-clients/troubleshooting.md

@@ -168,3 +168,106 @@ Causes
 
   - The client is performing an action that is taking longer than it
     should.
+
+# I don’t see my clients
+
+Here are common client troubleshooting steps you can work through to
+diagnose client install and communications problems.
+
+**Check that the client got installed**
+
+You should have something like:
+
+  - `C:\Windows\System32\GRR\3.1.0.2\GRR.exe` on windows;
+
+  - `/usr/lib/grr/grr_3.1.0.2_amd64/grrd` on linux; and
+
+  - `/usr/local/lib/grr_3.1.0.2_amd64/grrd` on OSX
+
+with variations based on the GRR version and architecture you installed
+(32bit is i386). If you didn’t get this far, then there is a problem
+with your installer binary.
+
+**Check the client is running**
+
+On linux and OS X you should see two processes, something like:
+
+    $ ps aux | grep grr
+    root       957  0.0  0.0  11792   944 ?        Ss   01:12   0:00 /usr/sbin/grrd --config=/usr/lib/grr/grr_3.1.0.2_amd64/grrd.yaml
+    root      1015  0.2  2.4 750532 93532 ?        Sl   01:12   0:01 /usr/sbin/grrd --config=/usr/lib/grr/grr_3.1.0.2_amd64/grrd.yaml
+
+On windows you should see a `GRR Monitor` service and a `GRR.exe`
+process in taskmanager.
+
+If it isn’t running check the install logs and other logs in the same
+directory:
+
+  - Linux/OS X: `/var/log/grr_installer.txt`
+
+  - Windows: `C:\Windows\System32\LogFiles\GRR_installer.txt`
+
+and then try running it interactively as below.
+
+**Check the client machine can talk to the server**
+
+The URL here should be the server address and port you picked when you
+set up the server and listed in `Client.control_urls` in the client’s
+config.
+
+    wget http://yourgrrserver.yourcompany.com:8080/server.pem
+    # Check your config settings, note that clients earlier than 3.1.0.2 used Client.control_urls
+    $ sudo cat /usr/lib/grr/grr_3.1.0.2_amd64/grrd.yaml | grep Client.server_urls
+    Client.server_urls: http://yourgrrserver.yourcompany.com:8080/
+
+If you can’t download that server.pem, the common causes are that your
+server isn’t running or there are firewalls in the way.
+
+**Run the client in verbose mode**
+
+Linux: Stop the daemon version of the service and run it in verbose
+mode:
+
+    $ sudo service grr stop
+    $ sudo /usr/sbin/grrd --config=/usr/lib/grr/grr_3.1.0.2_amd64/grrd.yaml --verbose
+
+OS X: Unload the service and run it in verbose
+    mode:
+
+    $ sudo launchctl unload /Library/LaunchDaemons/com.google.code.grr.plist
+    $ sudo /usr/local/lib/grr_3.1.0.2_amd64/grrd --config=/usr/local/lib/grr_3.1.0.2_amd64/grrd.yaml --verbose
+
+Windows: The normal installer isn’t a terminal app, so you don’t get any
+output if you run it interactively.
+
+  - Install the debug `dbg_GRR_3.1.0.2_(amd64|i386).exe` version to make
+    it a terminal app.
+
+  - Stop the `GRR Monitor` service in task manager
+
+Then run in a terminal as Administrator
+
+    cd C:\Windows\System32\GRR\3.1.0.2\
+    GRR.exe --config=GRR.exe.yaml --verbose
+
+If this is a new client you should see some 406’s as it enrols, then
+they stop and are replaced with sending message lines with increasing
+sleeps in between. The output should look similar to this:
+
+    Starting client aff4:/C.a2be2a27a8d69c61
+    aff4:/C.a2be2a27a8d69c61: Could not connect to server at http://somehost:port/, status 406
+    Server PEM re-keyed.
+    sending enrollment request
+    aff4:/C.a2be2a27a8d69c61: Could not connect to server at http://somehost:port/, status 406
+    Server PEM re-keyed.
+    sending enrollment request
+    aff4:/C.a2be2a27a8d69c61: Could not connect to server at http://somehost:port/, status 406
+    Server PEM re-keyed.
+    aff4:/C.a2be2a27a8d69c61: Sending 3(1499), Received 0 messages in 0.771058797836 sec. Sleeping for 0.34980125
+    aff4:/C.a2be2a27a8d69c61: Sending 0(634), Received 0 messages in 0.370272874832 sec. Sleeping for 0.4022714375
+    aff4:/C.a2be2a27a8d69c61: Sending 0(634), Received 0 messages in 0.333703994751 sec. Sleeping for 0.462612153125
+    aff4:/C.a2be2a27a8d69c61: Sending 0(634), Received 0 messages in 0.345727920532 sec. Sleeping for 0.532003976094
+    aff4:/C.a2be2a27a8d69c61: Sending 0(634), Received 0 messages in 0.346176147461 sec. Sleeping for 0.611804572508
+    aff4:/C.a2be2a27a8d69c61: Sending 0(634), Received 8 messages in 0.348709106445 sec. Sleeping for 0.2
+
+If enrolment isn’t succeeding (406s never go away), make sure you’re
+running a worker process and check logs in `/var/log/grr-worker.log`.

docs/developing-grr/contributing.md

@@ -1 +1,76 @@
-# Contributing code
+# Contributing Code
+
+GRR is a somewhat complex piece of code. While this complexity is
+necessary to provide the scale and performance characteristics we need,
+it makes it more difficult to get involved and understand the code base.
+So just be aware that making significant changes in the core will be
+difficult if you don’t have a software engineering background, or solid
+experience with python that includes use of things like pdb and
+profiling.
+
+That said, we want your contribution\! You don’t need to be a veteran
+pythonista to contribute artifacts or parsers. But whatever your
+experience, we strongly recommend starting somewhere simple before
+embarking on core changes and reading our documentation. In particular
+we recommend these as good starting points:
+
+  - Build a standalone console script to perform the actions you want. A
+    standalone console script won’t benefit from being able to be run as
+    a Collector or a Hunt, but it will get you familiar with the API,
+    and an experienced developer can convert it into a fully fledged
+    flow afterwards.
+
+  - Add to Artifacts or an existing flow. Many flows could do with work
+    to detect more things or support additional platforms.
+
+  - 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.
+
+The [Chromium](http://www.chromium.org/developers/contributing-code) and
+[Plaso](http://plaso.kiddaland.net/developer/style-guide) projects have
+some good general advice about code contributions that is worth reading.
+In particular, make sure you’re communicating via the dev list before
+you get too far into a feature or bug, it’s possible we’re writing
+something similar or have already fixed the bug.
+
+Code needs to conform to the [Google Python Style
+Guide](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html).
+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.
+
+We use the github [fork and pull review
+process](https://help.github.com/articles/using-pull-requests) to review
+all contributions.
+
+First, fork the [GRR repository](https://github.com/google/grr) by
+following [the github
+instructions](https://help.github.com/articles/fork-a-repo).
+
+Now that you have a github.com/your-username/grr repository:
+
+    # Make a new branch for the bug/feature
+    $ git checkout -b my_shiny_feature
+
+    # Make your changes, add any new files
+    $ git add newmodule.py newmodule_test.py
+
+When you’re ready for review, [sync your branch with
+upstream](https://help.github.com/articles/syncing-a-fork):
+
+    $ git fetch upstream
+    $ git merge upstream/master
+
+    # Fix any conflicts and commit your changes
+    $ git commit -a
+    $ git push origin HEAD
+
+Use the GitHub Web UI to [create and send the pull
+request](https://help.github.com/articles/using-pull-requests). We’ll
+review the change.
+
+    # Make review changes
+    $ git commit -a
+    $ git push origin HEAD
+
+Once we’re done with review we’ll commit the pull request.