Repository: falcon Updated Branches: refs/heads/master 941c4fa32 -> 645e13f50
FALCON-1934 Document Safemode in Falcon Server Author: bvellanki <[email protected]> Reviewers: "Ying Zheng <[email protected]>, Venkatesan Ramachandran <[email protected]>" Closes #140 from bvellanki/FALCON-1934 Project: http://git-wip-us.apache.org/repos/asf/falcon/repo Commit: http://git-wip-us.apache.org/repos/asf/falcon/commit/645e13f5 Tree: http://git-wip-us.apache.org/repos/asf/falcon/tree/645e13f5 Diff: http://git-wip-us.apache.org/repos/asf/falcon/diff/645e13f5 Branch: refs/heads/master Commit: 645e13f5016c2d7d4f2527d204dc11822c911182 Parents: 941c4fa Author: bvellanki <[email protected]> Authored: Fri May 13 15:43:59 2016 -0700 Committer: bvellanki <[email protected]> Committed: Fri May 13 15:43:59 2016 -0700 ---------------------------------------------------------------------- docs/src/site/twiki/FalconDocumentation.twiki | 40 ++++++++++++++++++++ docs/src/site/twiki/falconcli/FalconCLI.twiki | 1 + .../site/twiki/falconcli/SafemodeAdmin.twiki | 10 +++++ docs/src/site/twiki/restapi/AdminSafemode.twiki | 25 ++++++++++++ docs/src/site/twiki/restapi/AdminVersion.twiki | 8 ++++ docs/src/site/twiki/restapi/ResourceList.twiki | 1 + 6 files changed, 85 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/falcon/blob/645e13f5/docs/src/site/twiki/FalconDocumentation.twiki ---------------------------------------------------------------------- diff --git a/docs/src/site/twiki/FalconDocumentation.twiki b/docs/src/site/twiki/FalconDocumentation.twiki index 89370ec..ac7fa37 100644 --- a/docs/src/site/twiki/FalconDocumentation.twiki +++ b/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 http://git-wip-us.apache.org/repos/asf/falcon/blob/645e13f5/docs/src/site/twiki/falconcli/FalconCLI.twiki ---------------------------------------------------------------------- diff --git a/docs/src/site/twiki/falconcli/FalconCLI.twiki b/docs/src/site/twiki/falconcli/FalconCLI.twiki index ae2eb89..9ae0646 100644 --- a/docs/src/site/twiki/falconcli/FalconCLI.twiki +++ b/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 | ----------- http://git-wip-us.apache.org/repos/asf/falcon/blob/645e13f5/docs/src/site/twiki/falconcli/SafemodeAdmin.twiki ---------------------------------------------------------------------- diff --git a/docs/src/site/twiki/falconcli/SafemodeAdmin.twiki b/docs/src/site/twiki/falconcli/SafemodeAdmin.twiki new file mode 100644 index 0000000..5eb26c0 --- /dev/null +++ b/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 + http://git-wip-us.apache.org/repos/asf/falcon/blob/645e13f5/docs/src/site/twiki/restapi/AdminSafemode.twiki ---------------------------------------------------------------------- diff --git a/docs/src/site/twiki/restapi/AdminSafemode.twiki b/docs/src/site/twiki/restapi/AdminSafemode.twiki new file mode 100644 index 0000000..d7c9631 --- /dev/null +++ b/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> http://git-wip-us.apache.org/repos/asf/falcon/blob/645e13f5/docs/src/site/twiki/restapi/AdminVersion.twiki ---------------------------------------------------------------------- diff --git a/docs/src/site/twiki/restapi/AdminVersion.twiki b/docs/src/site/twiki/restapi/AdminVersion.twiki index 7db2d8f..d7615a0 100644 --- a/docs/src/site/twiki/restapi/AdminVersion.twiki +++ b/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" } ] } http://git-wip-us.apache.org/repos/asf/falcon/blob/645e13f5/docs/src/site/twiki/restapi/ResourceList.twiki ---------------------------------------------------------------------- diff --git a/docs/src/site/twiki/restapi/ResourceList.twiki b/docs/src/site/twiki/restapi/ResourceList.twiki index 5924834..aadd14f 100644 --- a/docs/src/site/twiki/restapi/ResourceList.twiki +++ b/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
