|
Cookbook /
WikiSh Installation & ConfigurationInstallation & Configuration of WikiShThis page gives more detailed installation & configuration instructions for WikiSh.
WikiSh is very configurable and takes security very seriously and as a result your installation options are numerous and flexible. We'll start with 6 example configurations (A-F) to give you an idea by example (if you want to go to one directly, I recommend the final one, F):
include_once("$FarmD/cookbook/toolbox.php"); // place this as early as possible in config.php
include_once("$FarmD/cookbook/WikiSh.php");
if (CondAuth($pagename,'admin')) {
$EnableWikiShWritePage = true; // allow admins to write to pages (1st layer of security)
$EnableWikiShCreatePage = true; // allow admins to create new pages (2nd layer, part A)
$EnableWikiShOverwritePage = true; //allow admins to overwrite existing pages (2nd layer, part B)
include_once("$FarmD/cookbook/SecLayer.php");
slParsePage($pagename, "SiteAdmin.WikiShAuth", $wshAuthPage);
}
In SiteAdmin.WikiShAuth you would put something like this (giving full access to WikiSh.* and only read access to *.*): WikiSh.*:append,prepend,insert,overwrite,create,delete *.*:read
include_once("$FarmD/cookbook/toolbox.php"); // place this as early as possible in config.php
include_once("$FarmD/cookbook/WikiSh.php");
include_once("$FarmD/cookbook/SecLayer.php");
if (CondAuth($pagename,'admin')) {
include_once("$FarmD/cookbook/WikiShCL.php");
$EnableWikiShWritePage = true; // allow admins to write to pages (1st layer of security)
$EnableWikiShCreatePage = true; // allow admins to create new pages (2nd layer, part A)
$EnableWikiShOverwritePage = true; //allow admins to overwrite existing pages (2nd layer, part B)
slParsePage($pagename, "SiteAdmin.WikiShAuth", $wshAuthPage);
}
slAddAuth($wshAuthPage, '*.*', 'read'); // add read privilege for everyone on all files
In SiteAdmin.WikiShAuth you would have something like this: *.*:append,prepend,insert,overwrite,create,delete
include_once("$FarmD/cookbook/toolbox.php"); // it is best to place this as early as possible in config.php
if (CondAuth($pagename,'admin')) {
include_once("$FarmD/cookbook/WikiSh.php");
include_once("$FarmD/cookbook/WikiShCL.php");
$EnableWikiShWritePage = true; // allow admins to write to pages (1st layer of security)
$EnableWikiShCreatePage = true; // allow admins to create new pages (2nd layer, part A)
$EnableWikiShOverwritePage = true; // allow admins to overwrite existing pages (2nd layer, part B)
$EnableWikiShChmod = true; // allow admins to change pmwiki authorizations (aka action=attr) on pages
include_once("$FarmD/cookbook/SecLayer.php");
slParsePage($pagename, "SiteAdmin.WikiShAuth", $wshAuthPage);
}
In SiteAdmin.WikiShAuth you would have something like this: *.*:append,prepend,insert,overwrite,create,delete,read
include_once("$FarmD/cookbook/toolbox.php"); // place this as early as possible in config.php
if ($Group == 'WikiSh' && CondAuth($pagename,'admin')) {
include_once("$FarmD/cookbook/WikiSh.php");
$EnableWikiShWritePage = true; // allow admins to write to pages (1st layer of security)
$EnableWikiShCreatePage = true; // allow admins to create new pages (2nd layer, part A)
$EnableWikiShOverwritePage = true; //allow admins to overwrite existing pages (2nd layer, part B)
$EnableWikiShChmod = true; // allow admins to change pmwiki authorizations (aka action=attr) on pages
include_once("$FarmD/cookbook/SecLayer.php");
slParsePage($pagename, "SiteAdmin.WikiShAuth", $wshAuthPage);
}
In SiteAdmin.WikiShAuth you would have something like this: *.*:append,prepend,insert,overwrite,create,delete,read
include_once("$FarmD/cookbook/toolbox.php"); // place this as early as possible in config.php
if ($Group == 'WikiSh' && CondAuth($pagename,'admin')) {
include_once("$FarmD/cookbook/WikiSh.php");
if ($pagename == 'WikiSh.ControlPanel')
include_once("$FarmD/cookbook/WikiShCL.php");
$EnableWikiShWritePage = true; // allow admins to write to pages (1st layer of security)
$EnableWikiShCreatePage = true; // allow admins to create new pages (2nd layer, part A)
$EnableWikiShOverwritePage = true; // allow admins to overwrite existing pages (2nd layer, part B)
$EnableWikiShTextWrite = true; // allow writing to text files
$EnableWikiShTextRead = true; // allow reading of text files
$EnableWikiShChmod = true; // allow admins to change pmwiki authorizations (aka action=attr) on pages
include_once("$FarmD/cookbook/SecLayer.php");
slParsePage($pagename, "SiteAdmin.WikiShAuth#page", $wshAuthPage);
slParsePage($pagename, "SiteAdmin.WikiShAuth#text", $wshAuthText);
}
In SiteAdmin.WikiShAuth you would have something like this: [[#page]] *.*:append,prepend,insert,overwrite,create,delete,read [[#text]] foo/*:append,prepend,insert,overwrite,create,delete,read
include_once("$FarmD/cookbook/toolbox.php");
include_once("$FarmD/cookbook/WikiSh.php");
include_once("$FarmD/cookbook/WikiShCL.php");
include_once("$FarmD/cookbook/SecLayer.php");
$EnableWikiShWritePage = true;
$EnableWikiShCreatePage = true;
$EnableWikiShOverwritePage = true;
if (CondAuth($pagename, "admin")) {
slAddAuth($wshAuthPage, "*.*", "read,create,insert,overwrite,append,prepend,attr,delete");
$EnableWikiShDeletePage = true;
$EnableWikiShChmod = true;
} else {
slAddAuth($wshAuthPage, "*.*", "read,create");
slAddAuth($wshAuthPage, "Test.*", "insert,overwrite,append,prepend,delete");
}
include_once("$FarmD/cookbook/powertools.php");
include_once("$FarmD/cookbook/MiscMX.php");
The configuration above, when placed in your config.php, is sufficient to start using WikiSh. If you want to further utilize the capabilities of SecLayer.php with this recommended configuration, then read on below... If you wanted to be able to manipulate your page authorizations by editing a page rather than through direct editing of the config.php you would use this code in config.php (in place of that above):
include_once("$FarmD/cookbook/toolbox.php");
include_once("$FarmD/cookbook/WikiSh.php");
include_once("$FarmD/cookbook/WikiShCL.php");
include_once("$FarmD/cookbook/SecLayer.php");
$EnableWikiShWritePage = true;
$EnableWikiShCreatePage = true;
$EnableWikiShOverwritePage = true;
slParsePage($pagename, "SiteAdmin.WikiShAuth#aliases", $wshAuthPage);
if (CondAuth($pagename, "admin")) {
slParsePage($pagename, "SiteAdmin.WikiShAuth#admin", $wshAuthPage);
$EnableWikiShDeletePage = true;
$EnableWikiShChmod = true;
} else {
slParsePage($pagename, "SiteAdmin.WikiShAuth#NONadmin", $wshAuthPage);
}
include_once("$FarmD/cookbook/powertools.php");
include_once("$FarmD/cookbook/MiscMX.php");
And then you would need to place this text in the page SiteAdmin.WikiShAuth: [[#aliases]] edit = append,prepend,insert,overwrite,create full = edit, read all = edit, delete, read, attr [[#admin]] *.*:all [[#NONadmin]] *.*:read Test.*:edit
include_once("$FarmD/cookbook/WikiShCL.php");
If you only want it to be included on a single page (such as WikiSh.ControlPanel) then you could use this instead (be sure you have previously included toolbox.php or in some other way resolved
if ($pagename == 'WikiSh.ControlPanel')
include_once("$FarmD/cookbook/WikiShCL.php");
include_once("$FarmD/cookbook/SecLayer.php");
$pagename = ResolvePageName($pagename); // this is unnecessary if you have already included cookbook/toolbox.php
slParsePage($pagename, "SiteAdmin.WikiShAuth#page", $wshAuthPage);
slParsePage($pagename, "SiteAdmin.WikiShAuth#text", $wshAuthText);
(:linebreaks:) [[#page]] edit = append,prepend,overwrite,insert,create all = edit,delete,attr,read *.*:read Test.*:all WikiSh.*:edit [[#text]] edit = append,prepend,overwrite,insert,create all = edit,delete,read mydir/hisdir/herdir/*:all
include_once("$FarmD/cookbook/SecLayer.php");
slAddAuth($wshAuthPage, "*.*", "read");
slAddAuth($wshAuthPage, "Test.*,WikiSh.*", "insert,append,prepend,overwrite,delete");
slAddAuth($wshAuthPage, "Test.*", "attr");
SecLayer also supports the concepts of priority and specific users (within authuser context). See SecLayer for more details.
$WikiShVars['ACTIVE'] = true;
$WikiShVars['HIST_PREFIX'] = "(:linebreaks:\n");
$WikiShVars['FAVSFILE'] = "Favorites"; // default to current group
$WikiShVars['HISTFILE'] = "History"; // default to current group
$WikiShVars['HISTSIZE'] = 100;
$WikiShVars['NOHIST'] = false;
$WikiShVars['AUTHOR'] = "WikiSh"; // default author
$WikiShVars['DEFAULT_DEBUG']= 5; // Print debug statements of this level
// and below. 1=detailed ... 5=nothing
$WikiShVars['DEBUGLEVEL'] = $WikiShVars['DEFAULT_DEBUG'];
$WikiShVars['DEBUG_OD'] = false; // true=use wshDbgOd() (SLOWS EVERYTHING!)
$WikiShVars['RC_DEBUG'] = 5; // normally no debug during RC
$WikiShVars['RANDOM_MIN'] = 0; // default minimum for random
$WikiShVars['RANDOM_MAX'] = 32768; // default maximum for random
$WikiShVars['PAGEVARS'] = 'post'; // "pre" "post" "prepost" "postpre"
$WikiShVars['LIST'] = ''; // like pagelist's list=X -- normal, etc.
$WikiShVars['SECONDS_START']= microtime(true;
$WikiShVars['SECONDSLEFT_START']= microtime(true;
Security:SECURITY NOTE on writing: If any write permission (whether wiki pages or text files) is given through the above $Enable... variables then it is strongly recommended to make this recipe available only on pages/groups which are password protected. SecLayer mitigates the threat to some degree, but you still need to be careful. SECURITY NOTE on text reading: If you allow text file reading ( Textfile access, whether reading or writing, should be used only with great caution. When accessing text files your access is limited only by the SecLayer restrictions and then the OS level file permissions. Unless you really know what you are doing you should not use this feature (textfile reading & writing).
SECURITY NOTE on forceread and forceedit: If you enable forceread or forceedit it must be from a page editable only by trusted authors. Otherwise undesired reads could be obtained or undesired page changes on pages that otherwise would be protected in this way. These "force" modes are very specific tools to be used with great care and only enabled on protected pages. Unless you really know what you are doing you should not use this feature. The default installation of WikiSh (if no changes are made to any $EnableWikiSh___ variables and no calls are made to slAddAuth() nor slParsePage) does not allow any writing to any page. Normally WikiSh will either be installed in this read-only mode or else giving administrators write authorization but not non-admin editors (or perhaps giving non-admin editors write authorization to just a few specific pages or groups). Giving broader write permissions to non-admin personnel opens you up to potential risk as significant damage can be done in a very short time via WikiSh. Security LevelsRecognizing the potential risk a scripting language presents in a collaborative environment such as a wiki page, WikiSh implements 4 different layers of security, particularly for write authorization to pages. ALL layers must be passed for a given page write. If a single layer is not passed then the write operation will not be allowed.
The following are some possibilities available for configuration using SecLayer (each example will be given from a config.php perspective and then from a SiteAdmin.WikiShAuth page perspective -- the administrator can choose how he/she wishes to configure the site. In each example on the SiteAdmin.WikiShAuth side (i.e., doing it via page and not via config.php) it is assumed that there is a call such as this within config.php): $pagename = ResolvePageName($pagename); // this is unnecessary if you have already included cookbook/toolbox.php slParsePage($pagename, "SiteAdmin.WikiShAuth", $wshAuthPage);
slAddAuth($wshAuthPage, 'WikiSh.*', 'insert,create,overwrite,append,prepend'); slAddAuth($wshAuthPage, '*.*', 'read'); edit=insert,create,overwrite,append,prepend WikiSh.*:edit *.*:read
slAddAuth($wshAuthPage, 'WikiSh.*,Test.*', 'read,insert,create,overwrite,append,prepend'); slAddAuth($wshAuthPage, '*.*', 'read'); edit=insert,create,overwrite,append,prepend WikiSh.*:edit Test.*:edit *.*:read
slAddAuth($wshAuthPage, 'WikiSh.*,Test.*,Finance.*,-Finance.MySalary', 'read,insert,create,overwrite,append,prepend'); edit=insert,create,overwrite,append,prepend WikiSh.*,Test.*,Finance.*:read,edit Finance.MySalary:-read,-edit Note that the dash can be placed either in front of the page/wildcard or in front of the authorization. Whether the authorization is an alias or a core authorization is irrelevant - it all just works. So you could have put the whole AuthPage in a single line and you could have separated the slAddAuth() code up into several different lines. The following are all functionally identical to this last example: insert,create,overwrite,append,prepend WikiSh.*,Test.*,Finance.*,-Finance.MySalary:read,edit edit=insert,create,overwrite,append,prepend AllButDelete = read,edit none=-read,-edit WikiSh.*,Test.*,Finance.*:AllButDelete Finance.MySalary:none edit=insert,create,overwrite,append,prepend WikiSh.*,Test.*,Finance.*,-Finance.MySalary:read WikiSh.*,Test.*,Finance.*,-Finance.MySalary:edit
$pagename = ResolvePageName($pagename); // this is unnecessary if you have already included cookbook/toolbox.php if ($pagename == 'Test.Foo') slAddAuth($wshAuthPage, 'SiteAdmin.PrivatePage', 'read,insert,create,overwrite,append,prepend,forceedit,forceread'); Note the "if" condition which prevents the "forceread" and "forceedit" capabilities being enabled for any other page other than Test.Foo. It is vital that Test.Foo be password protected from any edits! Configuring SecLayer via a wiki authorization page is certainly possible in this instance, but it must be carefully coordinated with the necessary conditions in config.php. Here is what config.php might look like: $pagename = ResolvePageName($pagename); // this is unnecessary if you have already included cookbook/toolbox.php slParsePage($pagename, "SiteAdmin.WikiShAuth#aliases", $wshAuthPage); slParsePage($pagename, "SiteAdmin.WikiShAuth#normal", $wshAuthPage); if ($pagename == 'Test.Foo') slParsePage($pagename, "SiteAdmin.WikiShAuth#Test-Foo", $wshAuthPage); Note again that all-important " And here is what SiteAdmin.WikiShAuth might look like to correspond with the above config.php section: [[#aliases]] edit=insert,create,overwrite,append,prepend all=edit,read [[#normal]] ... (whatever you might normally put in WikiSh permissions) [[#Test-Foo]] SiteAdmin.PrivatePage:all, forceread, forceedit You can see that there is significant flexibility in how you configure your authorizations. Any authorization line you can place in your page (as above) can be expressed equivalently using slAddAuth() if you prefer working in config.php. The only thing you cannot do with slAddAuth() is to define aliases (you may use any aliases which you have already defined through a call to slParsePage()).
slAddAuth($wshAuthPage, '*.*', 'read,insert,create,overwrite,append,prepend'); edit=insert,create,overwrite,append,prepend *.*:read,edit
|