Username Password
Bookmark and Share

WebGUI Config File

The WebGUI config file provides you with dozens of settings that will enable you to make WebGUI work how you want it to work. The usage of certain portions of the config file will be detailed in other chapters that relate to those specific sections, so if you need information not provided here you can take a look at the other chapters. This chapter is here to describe the uses of each of the available config file directives.



The sitename field is used throughout WebGUI for generating fully qualified URLs, and also doing hostname validation. This is a list, but generally only the first name in the list is used for most things. For example, the first name in the list is the one Spectre is going to attempt to contact when running a workflow.


"sitename" : [ "", ""],



This toggle enables SSL related features in WebGUI. Only enable it if you have configured a valid SSL certificate in Apache for this site.


"sslEnabled" : 0,



WebGUI uses a cookie to tie a session to a site visitor. The name of that cookie is traditionally wgSession. However, in some circumstances where you have other custom applications on the same domain, you may want the cookie to be a different name.


"cookieName" : "wgSession",



Normally WebGUI uses the full host and domain name that the site visitor visits the site with to set the cookie. For example it might use If you have multiple applications on various hostnames you may want to force the cookie to the domain name without the host.


"cookieDomain" : "",



Cookies expire after a certain amount of time. By default in WebGUI the cookie is set to expire after 10 years. However, in some environments, especially with shared computers, like a school, it's often better to expire the cookie after an hour, or after a day. Here are some examples:




1 hour


2 days


3 months


10 years


Until browser is closed



"cookieTTL" : "+10Y",



Normally WebGUI is installed to be the only application on a site. However, sometimes you may want to install it as a subdirectory on your site. If that's the case then you'd modify the gateway to match your subdirectory.


"gateway" : "/",



Windows and Mac OS X both use case insensitive file systems. This can cause problems for WebGUI. However, WebGUI can work around those problems if it knows about this problem. Set this if you're using an operating system with a case insensitive file system.


"caseInsensitiveOS" : "1",



The extras URL tells WebGUI where it should point a user's web browser to find all the images, javascripts, cascading style sheets, and other auxillary files that WebGUI needs to operate. Normally this is a relative URL because it's served from the same machine as WebGUI itself. However, you can provide a full URL if you serve all your static files from another machine, like


"extrasURL" : "/extras",



The local filesystem path that WebGUI needs in order to find the extras folder on the local machine.


"extrasPath" : "/data/WebGUI/www/extras",



The uploadsURL is the same as extrasURL, except it is for files that users upload to WebGUI.


"uploadsURL" : "/uploads",



The uploadsPath is the same as the extrasPath, except that it is for files that users upload to WebGUI.


"uploadsPath" : "/data/domains/",



This option tells WebGUI's rich editors to use the short human friendly asset URLs when linking to images and files rather than the URL to the uploads folder. The advantage to this is that the URLs are prettier, and they continue to work even if a user edits the image. However, it's slower than the default.


"richEditorsUseAssetUrls" : 0,



If you want to put WebGUI at the root of your site, but you want to serve up other applications and files outside of WebGUI, you can put those paths here.


"passthruUrls" : ["/icons", "/documentation/pdf", "/my-custom-application", "/server-status", "/perl-status"],


For each item in your passthruUrls directive, you'll also need to tell Apache that you want it to pass through, so configure a block like this in your Apache config:


<Location /documentation/pdf>
SetHandler None



This directive tells both WebGUI and Spectre what port to generate URLs for when connecting to the server.


"webServerPort" : 80,



The cacheType directive tells WebGUI which caching engine to use to cache data for a performance boost. In most situations you should use WebGUI::Cache::Database. But if you're running small sites (less than a few hundred pages, then WebGUI::Cache::FileCache will be faster.


"cacheType" : "WebGUI::Cache::FileCache",



If you are using WebGUI::Cache::FileCache, you can specify where to write the cache using this directive.


"fileCacheRoot" : "/path/to/cache",



If you use disableCache then all caching subsystems will be disabled in WebGUI. This is sometimes useful for troubleshooting, but it will severely impact the performance of your server.


"disableCache" : 0,



The dsn directive configures the database driver for WebGUI to use. You can tell it what database name to use, the hostname of the MySQL server, and even the port of the MySQL server.


"dsn" : "DBI:mysql:www_example_com;host=localhost",



This is the username that will be used to connect to the MySQL database.


"dbuser" : "webgui",



This is the password that will be used to connect to the MySQL database.


"dbpass" : "password",


dbSlave1, dbSlave2, dbSlave3

If you have database slaves, you can use them to improve performance slightly. You can configure up to three slaves using these directives.


"dbslave1" : {
"dsn" : "DBI:mysql:www_example_com;",
"user" : "webgui",
"pass" : "password"



The failoverdb directive says that if the master database cannot be connected to, then it should try to connect to this database.

If you are in an absolutely must never go down not even for a single request kind of environment, then you can use this option. However, there are usually better ways to accomplish what this function does. The biggest problem with this function is that if the master database only goes down for a little while, and then comes back up, there is no way to transfer the data that was written to the failover database back to the master in an automated fashion. You'll need to write scripts for this purpose. Or better yet, have use a more robust failover mechanism.


"failoverdb" : {
"dsn" "DBI:mysql:www_example_com;;port=3306",
"user" : "webgui",
"password" : "password"



If you're testing an email function, and don't wish to panic your users until after you've tested it, then use this directive to redirect all outgoing email to this address.


"emailOverride" : "",



If you want to require that no one can go into admin mode on your site unless they are within your network, then you can add a list of subnets in CIDR notation into this directive:


"adminModeSubnets" : [“”,””],



WebGUI allows for pluggable authentication modules. Specify the ones you wish to be used on your site here.


"authMethods" : [ "LDAP", "WebGUI" ],



WebGUI allows for multiple payment gateways. Use this directive to enable the ones you want to use.


"paymentPlugins" : ["Itransact","Cash"],



The commerce system also allows for multiple shipping gateways. Use this directive to enable those.


"shippingPlugins" : ["ByPrice", "ByWeight", "PerTransaction"],



By default WebGUI uses WebGUI::Asset::Template::HTMLTemplate as it's template parser. However, you can also use HTMLTemplateExpr and TemplateToolkit for more advanced templates. Or you could write your own.


"templateParsers" : ["WebGUI::Asset::Template::HTMLTemplate"],



In the event that no template parser is selected on a template, this directive will use the template parser you specify.


"defaultTemplateParser" : "WebGUI::Asset::Template::HTMLTemplate",



You can specify external programs to use to help index content in uploaded files. There is more on this directive in the Search Indexer chapter.


"searchIndexerPlugins" : {
"txt" : "/bin/cat",
"readme" : "/bin/cat",
"html" : "/bin/cat",
"htm" : "/bin/cat"



If you want to allow a maximum number of assets that a user can have on their site in order to force their site to remain small, then you can set this directive. Keep in mind that there are around 300 assets that come with WebGUI. If you set it to zero then the site may have an unlimited number of assets.


"maximumAssets" : 0,




Define Mobile Device's User Agent Strings. First,  you have to set "Use Mobile Style" to Yes inside the Admin console -> Settings -> UI first. If Mobile Device is detected, the "Mobile Style Template" and the "Mobile Template" will be used to render a page layout. Reference: "Use Mobile Style" and might be a good resource for latest mobile UA's regex matching update.

"mobileUserAgents" : [
"AvantGo", "DoCoMo", "Vodafone", "EudoraWeb", "Minimo", "UP\\.Browser", "PLink", "Plucker", "NetFront", "^WM5 PIE$", "Xiino", "iPhone", "Opera Mobi", "BlackBerry", "Opera Mini", "HP iPAQ", "IEMobile", "Profile/MIDP", "Smartphone", "Symbian ?OS", "J2ME/MIDP", "PalmSource", "PalmOS", "Windows CE", "Opera Mini" ],



This directive is a list of asset class names that are available to users to add to the site.


"assets" : [



This is the same as the assets directive, except that these assets are rarely used and therefore are only displayed in the asset manager view.


"utilityAssets" : ["WebGUI::Asset::Template", "WebGUI::Asset::RichEdit", "WebGUI::Asset::File::Image", "WebGUI::Asset::File"],



These assets act as containers for other assets. These assets are typically layout mechanisms rather than content.


"assetContainers" : [




The assetAddPrivilege directive allows you to define what group a user must be in to add given types of assets.


"assetAddPrivilege" : {
"WebGUI::Asset::Wobject::SQLReport" : 3,
"WebGUI:::Asset::Template" : 4



If this directive is enabled then WebGUI will show two buttons instead of the normal one save button on asset editing pages. The first is the normal save button, but the second is the “Save and Commit” button. The second button saves the current asset, and commits the version tag at the same time.


"enableSaveAndCommit" : 0,



This directive allows you to set the UI Level that the user must have in order to see a given asset type in the add content menu.


"assetUiLevel" : {
"WebGUI::Asset::Wobject::WSClient" : 7,
"WebGUI::Asset::RichEdit" : 4



Assets have a lot of common functions in their toolbars. This directive allows you to control what UI level your users must have to see each of the toolbar options.


"assetToolbarUiLevel" : {
"edit" : 1,
"delete" : 1,
"cut" : 1,
"copy" : 1,
"shortcut" : 5,
"editBranch" : 9,
"lock" : 5,
"export" : 9,
"changeUrl" : 9,
"promote" : 3,
"demote" : 3,
"manage" : 5,
"revisions" : 5,
"view" : 1


Asset Field UI Levels

It takes quite a bit of work, but you can specify the UI levels of every field in every asset. In this way you can truly customize the user experience. Here you can see examples on how to specify the UI levels for a couple of fields in two different assets.


"WebGUI_Asset_Wobject_Article_uiLevel" : { "menuTitle" : 9, "url" : 8 },

"WebGUI_Asset_RichEdit_uiLevel" : { "askAboutRichEdit" : 7, "preformatted" : 3 },



If you wish to export content to static files, then you need to specify the exportPath directive. The value is the location on the filesystem where the static files will be stored as they are exported.


"exportPath" : "/path/to/export",



If you are using the WS Client asset and wish to allow them to override the default mime types in SOAP/WSDL documents, then use this directive.


"soapHttpHeaderOverride" : 0,



Normally if a request comes into an asset URL and that URL represents a file or an image WebGUI will redirect the browser to the actual file URL. This is done because the redirect and subsequently letting Apache serve the file directly has far less impact on performance. However, in some circumstances, mostly for vanity sake, you may want WebGUI to actually serve the file itself. If you do, then enable this option. Be warned that this option quite adversely impacts performance.


"enableStreamingUploads" : "0",



This directive is a list of name/value pairs where the name is an alias that you want to be processed as a macro on your site, and the value is the filename of the macro code to execute. You are allowed to alias a single macro multiple times if your users are used to a particular name, or frequently like to use different names.


"macros" : {
"#" : "Hash_userId",
"/" : "Slash_gatewayUrl",
"@" : "At_username",
"AOIHits" : "AOIHits",
"AOIRank" : "AOIRank",
"AdminBar" : "AdminBar",
"AdminText" : "AdminText",
"AdminToggle" : "AdminToggle",
"AdSpace" : "AdSpace",
"AssetProxy" : "AssetProxy",
"CanEditText" : "CanEditText",
"D" : "D_date",
"EditableToggle" : "EditableToggle",
"Extras" : "Extras",
"FetchMimeType" : "FetchMimeType",
"FileUrl" : "FileUrl",
"GroupAdd" : "GroupAdd",
"GroupDelete" : "GroupDelete",
"GroupText" : "GroupText",
"H" : "H_homeLink",
"International" : "International",
"L" : "L_loginBox",
"LastModified" : "LastModified",
"LoginToggle" : "LoginToggle",
"Page" : "Page",
"PageTitle" : "PageTitle",
"PageUrl" : "PageUrl",
"RandomAssetProxy" : "RandomAssetProxy",
"RandomThread" : "RandomThread",
"RootTitle" : "RootTitle",
"Spacer" : "Spacer",
"SubscriptionItem" : "SubscriptionItem",
"SubscriptionItemPurchaseUrl" : "SubscriptionItemPurchaseUrl",
"Thumbnail" : "Thumbnail",
"User" : "User",
"a" : "a_account",
"c" : "c_companyName",
"e" : "e_companyEmail",
"r" : "r_printable",
"u" : "u_companyUrl"



Using the ldapAlias directive you can specify field matches between WebGUI profile fields and an LDAP attributes. This is useful when combined with the LDAP synching workflow activities.


"ldapAlias" : {
"firstName" : "givenName",
"lastName" : "sn",
"email" : "mail",
"companyName" : "o"



This directive is a list of subnets specified in CIDR notation that WebGUI should expect Spectre to connect from. Any connections from subnets other than these will be rejected by WebGUI.


"spectreSubnets" : [ "" ],



When WebGUI connects to Spectre what IP address should it use?


"spectreIp" : "",



This directive goes along with spectreIp to tell WebGUI how to connect to Spectre.


"spectrePort" : 32133,



The workflowActivities directive allows you to configure which workflow activities are available to which object types for your users to build new workflows.


"workflowActivities" : {
"None" : [
"WebGUI::User" : [
"WebGUI::VersionTag" : [



WebGUI has a built in graphing system that can be extended with new plugins. Currently it is only used in the Poll, but it may also be used in custom applications. Here you can specify a list of plugins that can be used to generate graphs.


"graphingPlugins" : [



If you install the C program aspell and the Text::Aspell Perl module, you can enable WebGUI's built in spell checking system. You simply need to use this directive to tell it which dictionaries are available on your system.


"availableDictionaries" : [
"id" : "en_US",
"name" : "English",
"default" : "1"
"id" : "nl",
"name" : "Dutch"



This specifies a script to be executed as the user logs in to WebGUI. You can use macros in the command and they will be processed.


"runOnLogin" : "/path/to/ --user=^@;",



This specifies a script to be executed as a user logs out of WebGUI. You can use specify macros in the command and they will be processed.


"runOnLogout" : "/path/to/ --user=^@;"

Keywords: config settings

0jasamper2000: ";keyword=config"
Search | Most Popular | Recent Changes | Wiki Home
© 2022 Plain Black Corporation | All Rights Reserved