FALCON-1934 Document Safemode in Falcon Server

Author: bvellanki <bvellanki@hortonworks.com>

Reviewers: "Ying Zheng <yzheng@hortonworks.com>, Venkatesan Ramachandran <vramachandran@hortonworks.com>"

Closes #140 from bvellanki/FALCON-1934

docs/src/site/twiki/FalconDocumentation.twiki

@@ -91,6 +91,46 @@ Startup property file in both falcon & prism server need to be configured with t
 
 ---++++ Prism Setup
 <img src="PrismSetup.png" height="400" width="600" />
+
+---+++ Safe Mode
+Safemode is useful when the admin wants to prevent Falcon users from scheduling entities in the workflow engine. This can happen when
+   * Hadoop clusters are being upgraded.
+   * Falcon cluster entities are being updated.
+
+When in Safemode, users can only perform limited operations. To be specific,
+   * Users can perform read operations on entities subject to authorization.
+   * Superuser can perform cluster entity update operation.
+   * Suspend/Kill of individual instances will be allowed if users want to suspend specific job operations.
+   * Suspend operation on schedulable entities will be allowed. This is because, a user might want to suspend entities during rolling-upgrade to handle jobs incompatible with updated versions.
+   * All other operations are not allowed. To enumerate,
+      * All entity submit, submitAndSchedule operations are not allowed.
+      * Entity operations not allowed are : update, schedule, touch, delete, submit, submitAndSchedule, resume
+      * Instance operations not allowed are : rerun, resume
+
+---++++ Getting into/out-of Safemode.
+The Falcon process user can specify whether to start Falcon in safemode with the following command:
+<verbatim>
+<falcon-server>/bin/falcon-start -setsafemode <true/false>
+</verbatim>
+
+A superuser or admin-user can set Falcon server into/outof safemode using CLI or RestAPI. A user is considered superuser if they
+owns the Falcon process or belong to group specified in startup property falcon.security.authorization.superusergroup. A user is
+considered admin user if they are listed under startup property falcon.security.authorization.admin.users, OR they belong to group
+listed under startup property falcon.security.authorization.admin.groups.
+
+<verbatim>
+## CLI
+<falcon-server>/bin/falcon admin  [-setsafemode <true/false>]
+
+## RestAPI
+GET http://falcon-server:15000/api/admin/setSafeMode/true
+OR
+GET http://falcon-server:15000/api/admin/setSafeMode/false
+</verbatim>
+
+*NOTE* User can find if FalconServer is in safemode or not, by calling the [[restapi/AdminVersion][Admin Version]] API. Once
+server is set to safemode, this state is persisted during restarts. It has to be unset explicitly if user wants to exit safemode.
+
 
 ---+++ Configuration Store
 Configuration store is file system based store that the Falcon system maintains where the entity definitions

docs/src/site/twiki/falconcli/FalconCLI.twiki

@@ -102,6 +102,7 @@ $FALCON_HOME/bin/falcon entity -submit -type cluster -file /cluster/definition.x
 |[[HelpAdmin][Help]]                             | Return help options                             |
 |[[VersionAdmin][Version]]                       | Return current falcon version                   |
 |[[StatusAdmin][Status]]                         | Return the status of falcon                     |
+|[[SafemodeAdmin][SetSafeMode]]                  | Set/unset Falcon Server in safemode             |
 
 -----------
 

docs/src/site/twiki/falconcli/SafemodeAdmin.twiki

@@ -0,0 +1,10 @@
+---+++SetSafeMode
+
+[[CommonCLI][Common CLI Options]]
+
+When -setsafemode is true, Falcon starts in safemode.
+When -setsafemode is false, falcon starts in normal mode.
+
+Usage:
+$FALCON_HOME/bin/falcon admin -setsafemode true/false
+

docs/src/site/twiki/restapi/AdminSafemode.twiki

@@ -0,0 +1,25 @@
+---++  GET /api/admin/setSafeMode/:mode
+   * <a href="#Description">Description</a>
+   * <a href="#Parameters">Parameters</a>
+   * <a href="#Results">Results</a>
+   * <a href="#Examples">Examples</a>
+
+---++ Description
+Set falcon server into/out of safemode.
+
+---++ Parameters
+   * :mode true/false.
+   * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system.
+
+---++ Results
+The value of FalconSever safemode.
+
+---++ Examples
+---+++ Rest Call
+<verbatim>
+GET http://localhost:15000/api/admin/setSafeMode/true
+</verbatim>
+---+++ Result
+<verbatim>
+true
+</verbatim>

docs/src/site/twiki/restapi/AdminVersion.twiki

@@ -29,6 +29,14 @@ GET http://localhost:15000/api/admin/version?doAs=joe
         {
             "key":"Mode",
             "value":"embedded"
+        },
+        {
+            "key":"authentication",
+            "value":"simple"
+        },
+        {
+            "key":"safemode",
+            "value":"false"
         }
     ]
 }

docs/src/site/twiki/restapi/ResourceList.twiki

@@ -39,6 +39,7 @@ The current version of the rest api's documentation is also hosted on the Falcon
 | GET         | [[AdminStack][api/admin/stack]]                | Get stack of the server                     |
 | GET         | [[AdminVersion][api/admin/version]]            | Get version of the server                   |
 | GET         | [[AdminConfig][api/admin/config/:config-type]] | Get configuration information of the server |
+| GET         | [[AdminSafemode][api/admin/setSafeMode/:mode]] | Set safemode to true/false in falcon server |
 
 ---++ REST Call on Entity Resource