Added some extra content to the misp-book

- some administrative tips & tricks
- Added Appendix A: External authentication

SUMMARY.md

@@ -8,3 +8,4 @@
 * [Administration](administration/README.md)
 * [Automation and MISP API](automation/README.md)
 * [Categories and Types](categories-and-types/README.md)
+* [Appendices](appendices/README.md)

administration/README.md

@@ -415,6 +415,49 @@ This will give you a top 10 table per ip and username:
 +----------------+----------------------------------+------+
 ```
 
+#### MISP Logs
+
+By default, MISP has several layers of logs that can be used to trouble-shoot and to monitor the system. Let's walk through each of the available logs:
+
+*   **Apache access logs**: Rotating logs generated by apache, logging each request, by default (on Ubuntu) they are found in /var/log/apache2/misp.local\_access.log. The location can be changed via the apache conf file
+*   **Apache error logs**: Rotating logs generated by apache, logging error messages, by default (on Ubuntu) they are found in /var/log/apache2/misp.local\_error.log. This error log file will generally not be used by MISP, however, if there is a PHP level error that prevents MISP from functionining you might have relevant entries here.
+*   **MISP error log**: Generated by MISP, logging any exceptions that occur during usage. These can be found in /var/www/MISP/app/tmp/logs/error.log (assuming default installation path). If you are seeins errors in here and are stuck with an issue let us know via github!
+*   **MISP debug log**: Generated by MISP, any debug messages and Notice level messages will be sent to this file. Generally less interesting, but can be helpful during debuging sessions. It should not be necesary to monitor this under normal usage. The file can be found in /var/www/MISP/app/tmp/logs/debug.log (assuming default installation path).
+*   **MISP worker error log**: Generated by MISP background workers, logging any exceptions generated during a background job. It is the equivalent of the MISP error log for background jobs, so if scheduled tasks, synchronisation or e-mailing with the workers enabled are causing issues, this is the place to check. It can normally be found at /var/www/MISP/app/tmp/logs/resque-worker-error.log
+*   **MISP worker logs**: Rotating logs generated by MISP background workers, logging any jobs executed by workers. This is part of the normal operation of background workers and doesn't have to be monitored, though it can help when debugging issues. Normally found at /var/www/MISP/app/tmp/logs/resque-[current date].log
+*   **MISP scheduler error log**: Generated by MISP scheduler worker, logging any exceptions generated during the scheduling of a background job. It is the equivalent of the MISP error log for scheduled jobs. It can normally be found at /var/www/MISP/app/tmp/logs/resque-scheduler-error.log
+*   **MISP scheduler logs**: Rotating logs generated by MISP scheduler worker, logging any schedulings of jobs to be executed by workers. This is part of the normal operation of the scheduler worker and doesn't have to be monitored, though it can help when debugging issues. Normally found at /var/www/MISP/app/tmp/logs/resque-scheduler-[current date].log
+
+#### Logging of failed authentication attempts
+
+By default, MISP logs all failed login and authentication attempts in the built in Audit logs. To view any such failed attempts, simply log in as a site admin and navigate to Audit - List logs. 
+
+There are two types of entries that will be interesting if you are looking for failed authentication attempts, entries of action "auth\_fail" (for failed attempts to authenticate via the API key or the external authentication system) and login\_fail (for failed login attempts via the login page).
+
+You can also search for any such entries using the Search Logs feature, simply choose the desired action from the two listed above and hit search. 
+
+What is logged:
+
+```
++----------------+------------+---------------------------+----------+
+| Auth method    | Action     | Failed credentials logged | IP       |
++----------------+------------+---------------------------+----------+
+| Webform        | login_fail | None                      | Optional |
+| API            | auth_fail  | API key                   | Optional |
+| Webform        | auth_fail  | External auth key         | Optional |
++----------------+------------+---------------------------+----------+
+```
+
+In order to enable IP logging for any logged request in MISP, navigate to Administration - Server settings - MISP settings and enable the MISP.log\_client\_ip setting.
+
+It is also possible to enable full logging of API and external authentication requests using the MISP.log\_auth setting in the same location, but keep in mind that this is highly verbose and will log every request made. In addition to the information above, all accessed resource URLs are also logged. 
+
+#### Clearing expired sessions
+
+By default the garbage collection of sessionsis disabled in PHP. It is possible to enable it, but it's not recommended and as such MISP provides a manual way of clearing the sessions. 
+
+Navigate to the diagnostics screen of MISP (Administration - Server settings - Diagnostics) and near the bottom of the page there will be a counter showing the count of currently stored expired sessions. Simply purge them by clicking the applicable button when the number grows too large. 
+
 #### Troubleshooting MISP not connecting to redis but redis-cli working
 
 If you have an IPv6 enabled OS, but an older redis version that does not support IPv6 (<v2.8), MISP might fail to connect to the redis server while redis-cli is working.

appendices/README.md

@@ -0,0 +1,45 @@
+# Appendix A: External Authentication
+
+#### The external authentication mechanism described
+
+The external authentication allows a user or an external tool to authenticate with MISP using an arbitrary value passed along in a custom header. This authentication method overrides the regular authentication mechanisms and is customisable by a site-admin. 
+
+It is possible to create a mixed mode MISP setup where certain users can go through the normal authentication mechanism and other users are required to use the external authentication method.
+
+#### Setting up the external authentication mechanism
+
+To change the authentication settings, navigate to Administration - Server settings - Plugin settings
+
+The settings associated with the external authentication can be found by pressing the CustomAuth button as depicted below:
+
+![The server settings relevant to the Custom Authentication system.](figures/a/settings.png)
+
+To change a setting simply double click on the value to edit the field. Use the guidance provided by the setting tool to configure the external authentication. The accessible settings are as follows:
+
+*   **enable**: Enable or disable external authentication (off by default)
+
+*   **header**: The header which MISP will use to identify users
+
+*   **required**: Enabling this setting will force all users to use the external authentication. Leave this disabled allows administrators to assign external authentication or regular authentication users.
+
+*   **only_allow_source**: Setting a url / IP address here will only allow requests that originated from the given address
+
+*   **name**: The name to be used for the authentication mechanism. This is reflected in the user creation / edit views, the logs and the error messages on failed logins.
+
+*   **disable_logout**: Disable the default logout button. Using an external authentication mechanism that authenticates via the header with each requests makes the logout button obsolete. 
+
+*   **custom_password_reset**: If your authentication system has a url that a user can access to reset his/her password, please specify the full url for it here. This will then be reused in the UI.
+
+*   **custom_password_logout**: If your authentication system has a url that a user can access to logout, please specify the full url for it here. This will then be reused in the UI.
+
+#### User management
+
+Using a new setting, user self management can be disabled for all users that are not administrators via the MISP.disableUserSelfManagement setting, found in the MISP settings tab. Enabling this setting removes the ability of users to change their user settings and reset their authentication keys. All other functionality remains unchanged.
+
+![Adding a user with the external authentication enabled.](figures/a/add_user.png)
+
+To create an external authenticated user, simply tick the External authentication user checkbox, after which an external auth key field will appear. This will be used to identify the users via the passed along header. 
+
+#### Logging
+
+For a description of the logging facilities provided by this plugin, please refer to the "Logging of failed authentication attempts" section of the Administration section.