admin_tool3Add my vote for this tag installation2Add my vote for this tag create new tag
, view all tags
ALERT! NOTE: This is a HistoricalDocument topic. It used to be distributed in an earlier TWiki release, but is no longer part of the official TWiki distribution. Post questions, error notes, and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

ALERT! NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

TWiki Admin Cook Book

This page has many tips and tricks, particularly useful when you're installing TWiki for the first time. This guide is most useful before or immediately following a TWiki installation!

See also:

Tag Cloud on "admin_tool"

During Installation

Create custom skin

In an Intranet environment it helps "sell" TWiki if it looks like the Intranet. Consider creating a custom TWiki skin.

Rename Main web to User web

You can rename the Main web to User. It will make WikiWord links to usernames more meaningful (User.UserName instead of Main.UserName); but does not bring much gain for other types of topics like (User.EngineeringGroup or User.TokyoOffice). Just rename data/Main to data/User, and change $mainWebname variable in lib/TWiki.cfg file. Signatures in all existing topics need to be fixed as well.

See also TWiki:Codev.RenameMainWebToHome, TWiki:Codev.RenameTheMainWeb, TWiki:Codev.SeparateHowtoWeb for arguments pro and con.

Help with remembering passwords

Users keep Forgetting Passwords (see TWiki:Codev.ForgettingPasswords ). When demonstrating TWiki to new users and/or helping them with TWikiRegistration, do not forget to show the user how to use the "remember my password" feature in their browser.

A quick way to check the guest password is to view the .htaccess file.

AuthName 'TWiki UserName (i.e. TWikiGuest/guest)'

HELP Hint: In a behind firewall setting it is better to configure TWiki to use an existing directory (NIS, LDAP, Active Directory) so that users do not need to remember multiple passwords.

How to deal with robots that try to index a public TWiki site

Dealing with Robots

Robots crawling and prowling a public TWiki site can have a significant impact on the CPU load. You can see what is happening on your site by reading the file twiki/data/log<YYYYMM>.txt. You might see hundreds of hits per hour by robots. When rdiff or search are used by the robots, a site may consume 70 or 80 percent of the system resource.

The robot problem is caused by several issues which can be dealt with separately

  1. Your TWiki exposes many links to robots, and simply answering them takes a lot of computer time. Even if you do want to have all that available, you want it to go as fast as possible.
  2. Many of the things robots try to grab are inappropriate for them. We don't want them searching or running recursive differences.
  3. The default TWiki install includes lots of files & links that many people may not want. So you can cut down on traffic by blocking those links.

Subdividing the "approaches" to these problems, here we go!

  1. Robots try to grab stuff that they should not have.
    1. Fix the WebLeftBar and the WebBottomBar so that they DO NOT show links to casual visitors. If a robot does not find a "search" button, then it cannot waste your CPU by trying to use it.
    2. In the bottom bar, have a new regime that shows only a "Login" button. Only after a person logs in (TWiki:Plugins.SessionPlugin or ordinary htauthentication is OK), does one see links to Edit and such. You can use the SpreadSheetPlugin to make a conditional display. It does not show the "good stuff" to TWikiGuest.
    3. Hide WebChanges. Hide WebTopicList. Hide WebIndex. My WebLeftBar is reconfigured to expose less stuff. Especially pages that rely on searches. Go through your webs and try to get rid of miscellaneous links to WebTopicList or WebIndex. Create one topic, and one topic only, that has that information. That new topic, called WebGuide, is liberally linked and available from the left bar. However, the difference is that the WebGuide topic does not have point-and-click links. Instead, it just gives users a line they can type into the web browser URL so they can conduct the search they want.
    4. Use the TWiki:Plugins.VarCachePlugin to cache topics that consume CPU time, such as WebTopicList and WebIndex
    5. If you are a site administrator, there is a file called "robots.txt" that sits at the top level of the web server's public space. Robots are supposed to read that file and respect its prohibitions. Some robots ignore it. Add a substantial list of things to your robots.txt file. Ban all robotic uses of any TWiki feature except view. No edit, rdiff, search, or any of that other stuff.

Tip, idea One way for a public site using authentication to hide the topic actions menu in the footer using CSS is to modify the div class="patternTopicActions" in twiki.pattern.tmpl at around line 20 and insert

style="display:%IF{"context authenticated" then="block" else="none"}%"

Sorting Recent Changes

How to allow the "Recent Changes" table to be sortable by columns other than modified date.

Rather than changing the search template, you can change WebChanges to use FormattedSearch instead. The results are now formatted as a single TWiki table, which allows sorting by any column. Of course, this only applies to recent changes, not generic searches.

Here are the contents of the topic:

<div id="searchtable">
%N% Click on a column heading to sort the results by topic name or modifier name (instead of modified date). Click the heading again to reverse the sort.
%TABLE{ sort="on" tableborder="0" cellpadding="5" cellspacing="0" headerbg="white" headercolor="black" databg="white" headerrows="1" footerrows="0" }%
%SEARCH{".*" web="%INCLUDINGWEB%" regex="on" nosearch="on" order="modified" reverse="on" limit="%URLPARAM{"limit" default="50"}%" header ="| *Topic* | *Changed<br>(now %DISPLAYTIME{"$hou:$min"}%)* | *Changed by* |" format="|<a href=$topic title=$topic>$topic(40, ...)</a><br>$summary(80) |$date - $percntCALC{$IF($EXACT(1.1, $rev), <b>NEW</b>, r$rev [[%SCRIPTURL%/rdiff%SCRIPTSUFFIX%/$web/$topic (diff)]])}$nop% |$wikiusername |" }%</div>


   * See [[%SCRIPTURL%/view%SCRIPTSUFFIX%/%INCLUDINGWEB%/%INCLUDINGTOPIC%?limit=all][all]] changes

#searchtable th {
  font-size: 125%;
  border-top: 3px solid #8caae6;
  border-bottom: 3px solid #8caae6;
#searchtable {
  padding-bottom: 1em;
  border-bottom: 3px solid #8caae6;
#searchtable th A:link, th A:visited, th A:active { text-decoration: none; }
#searchtable th A:hover { text-decoration: underline; }

Here are some details:

  • CSS markup is used to make the results look somewhat similar to the original search results.
  • The topic name is truncated to eliminate the "page dropping down in IE" issue in TWiki:Plugins.BlueSkin. The full name is shown as a tooltip on mouse hover. This is identical to the Outlook behaviour for long subject lines.
  • The topic summary is not in a separate row anymore, since that messes up the sorting.
  • The revision summary is presented as DATE - TIME - REV (diff), to keep the sorting consistent.

Before First Presentation

Tips about first presentation -- ATasteOfTWiki is a handy presentation you can give to your users. Read also TWiki:Sandbox.TWikiCourseOutlineExample2 and TWiki:Codev.HowToGetInternalBuyInForTWiki. The TWiki:Codev.TWikiPresentation05Aug2004 talk given by TWiki:Main.PeterThoeny during LinuxWorld gives some background on TWiki collaboration.

How to build participation: read WikiOrg:TipsForSiteOperators - advice directly from Ward Cunningham, author of Wiki concept and first Wiki.

Consider installing #CommentPlugin and #SlideShowPlugin before your first demo.

Simplify menu in page templates

How to get nice pages with simpler menu options for beginners

A Skin is TWiki's way to present different system-generated formats (like header/footer/sidebar menu) and exactly the same information from the page body (see TWikiSkins). The "Classic" TWiki skin is oriented towards advanced power users. Newbies may feel overwhelmed by the number of options. Many simpler custom skins are in development at TWiki:Plugins.WebHome. Consider using a simpler custom skin to make a better "first impression": TWiki is simple to use.

There is currently a discussion at TWiki:Codev.SimplerDefaultTemplates about simpler default template for TWiki:Codev.SimplerTWikiDistribution.

Customize tutorial for beginners

Select simpler skin and customize beginner's help topics accordingly.

Ongoing admin tasks

Admin Tools

AdminTools has most of the tools you need to administer a TWiki site - on one page. You can link it from SiteMap.

Best of Plugins

With more than 170 TWiki plugins (and counting), there are a lot to choose from. Plugins are mainly contributed by TWiki users who are software developers. Plugins are a relatively new TWiki addition, so there are fewer established standards than for the core TWiki code. This means that not all plugins are equal in ease of installation, operation, or compatibility with each other. Here are selected plugins that are reliable, easy-to-use and offer basic enhanced functionality.

CommentPlugin -- TWiki:Plugins.CommentPlugin

User-friendly alternative of Edit, without losing Wiki spirit. Comments can be entered in a conventional Web form style with a text box and a submit button. This is all displayed on a TWiki page without having to use TWiki's Edit. Text added appears exactly as if edited normally, and topic can be edited also using the full TWiki Edit. This is useful to encourage participation among your users who are not yet comfortable with TWiki capabilities.

SlideShowPlugin -- TWiki:Plugins.SlideShowPlugin

This Plugin allows you to convert topics with headings into web based presentations. This is a useful alternative to PowerPoint, especially if you need to link to related content.

SpreadSheetPlugin -- TWiki:Plugins.SpreadSheetPlugin

This Plugin allows you to add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in TWiki topics.

TablePlugin -- TWiki:Plugins.TablePlugin

A must-have, this Plugin allows you to control attributes of tables and sorting of table columns.

TopicVarsPlugin -- TWiki:Plugins.TopicVarsPlugin

This lets you create variables, like a graphics icon library, in any topic - instead of only in WebPreferences - and refer to them from other topics within the same web.

TWiki-based Applications

TWiki can be used as a platform to build web applications, also called TWiki:Codev.TWikiApplications.

Sample applications

Adding extra input boxes to your edit screen that write to the text

It's often the case that when you are building TWiki:Codev.TWikiApplications, there are frequently used constructs that you want to add to the text - for example, searches, or actions, or other complex tags.

It's really not hard to add support for this to your edit skin.

The following example adds an action entry box to the edit template. It can be done by adding the following to the edit.pattern.tmpl, though it could of course be included from another topic or via a %TMPL:DEF definition.

<h3>Add action</h3>
Who: <input type="text" value="" name="action_who" />
Due: <input type="text" value="" name="action_due" /><br />
<textarea wrap="virtual" rows="3" cols="70" value="" name="action_desc">
<input type="button" value="Add action" onClick="document.main.text.value+='%ACTION{'+' due=\''+document.main.action_due.value+'\''+' who=\''+document.main.action_who.value+'\''+'}% '+document.main.action_desc.value.replace(/\n/g,'<br />')+'\n'" />
want to add extra functionality to skins, to support the adding of formatted text entered 

and it looks like this:

Add action

Who: Due:

Please add your favorite TWiki tips/trick to TWiki:TWiki.TWikiAdminCookBook to help the next new TWiki admin. (One BIG area: include pages of implemented basic SEARCHes, like, to generate a straight TOPICS list (alphabetical web topic titles only); also, simple combos of forms + search, like one- and two-category forms to use to classify pages, and then searches to find and display in few useful formats; more in that general area.)

-- Contributors: TWiki:Main.CrawfordCurrie, TWiki:Main.GrantBow, TWiki:Main.JonReid, TWiki:Main.MikeMannix, TWiki:Main.MikeMaurer, TWiki:Main.PankajPant, TWiki:Main.PaulJohnson, TWiki:Main.PeterMasiar, TWiki:Main.PeterThoeny

Comments & Questions about this Supplemental Document Topic

Whoa, on first look it's quite a change! I'll look it over more closely soon. Good work!

-- GrantBow - 17 Jan 2003

JaneJennings published a mini-howto for making a simplified site based on a 'standard' installation. It's not available! And she removed her email address from her Twiki homepage - no way to contact her. Sorry! Commented out.

I assume all this discussion will be automagically removed when generating copy of this page for distro, right? So I do not have to clean it manually?

-- PeterMasiar - 17 Jan 2003

Correcting grammar and typos. I wish this was in a better state for including since the content is SO USEFUL.

-- GrantBow - 26 Jan 2003

I corrected some grammar, wording, and formatting where appropriate. I upped the number of plugins to "more than 60" as there are now ~65. I also updated all the InterWiki links to use the new TWiki:Web.Topic syntax as per BeijingRelease. I think this is pretty close to "clean" gramatically, but it would be good if one or two more people give it a look.

-- MikeMaurer - 30 Jan '03

Thank you, Peter, Grant and Mike - and all others who read the docs and did not find anything fixable. I feel strongly this page is important to new admins and was afraid it could be not included. Together, we made it!

-- PeterMasiar - 07 Feb 2003

This topic is misnamed. Administration is an ongoing/periodic activity. The existance of this topic as TWikiAdminCookBook makes it hard to place tips like HowToDeleteUserAccount

-- MattWilkie - 21 Jul 2003

I added one more header section for ongoing admin activities. Matt, can you please refactor HowToDeleteUserAccount there - so all tips & recipies for admin will be in one place (if you like if of course).

-- PeterMasiar - 22 Jul 2003

I created a new topic especially for ongoing maintenance tasks like deleting user accounts. It's named ManagingUsers at the moment but I've asked for it to be renamed ManagingUsers. The maintenance guide is INLCUDEd in this topic. Note the "edit this section" link which takes one directly to the sectional page.

I couldn't make up my mind if AdminTools should be in the Maintenance Guide or not so I left it out. What do you think?

-- MattWilkie - 13 Aug 2003

The MaintenanceGuide containing the "Removing User Accounts" section was included in this cookbook. I renamed MaintenanceGuide to ManagingUsers and took it into the TWiki reference manual. I deleted the "Removing User Accounts" section from this cookbook since it is no longer needed.

-- PeterThoeny - 15 Aug 2004

I moved three TWikiTipsOfTheDay entries to this cookbook topic. I do not want to intimidate new users with details administrators are interested to know.

-- PeterThoeny - 21 Jul 2005

I'm creating a new topic, NewTWikiAdminSteps, with some additional important information for new TWiki Admins. I'm hoping that this is the first step towards documentation improvement. If you have suggestions for additional places to link to my new topic from, please feel free to add them. smile

-- AmandaSmith - 15 Feb 2006

In the section on How to deal with Robots you say "Fix the WebLeftBar and the WebBottomBar so that they DO NOT show links to casual visitors." Great advice!

Now, for those of us who've only been using TWiki for three days and haven't earned our TWiki Ph.D. yet - could you "Pretty-Please with sugar on top" add a link to something that explains How-To?

-- TerrillBennett - 13 Jun 2007

Thanks for the candid feedback. This document is a bit dated and needs some overhaul. Please feel free to help out in improving the doc.

-- PeterThoeny - 14 Jun 2007

Always glad to help, when and where I can... and I will, as I learn to solve problems. But, being only 5 days old, I still don't know how to fix the WebLeftBar / WebBottomBar. If anyone does know, could you add the step-by-step? I'll add raw Brown Sugar instead of that white processed stuff!-)

-- TerrillBennett - 14 Jun 2007

I prefer Lindth chocolate smile

Not sure I understand the issue. Every TWiki web has a WebLeftBar topic that has frequently used links. Visit that topic (e.g. by typing WebLeftBar in the Jump box), and edit it to modify the links.

-- PeterThoeny - 15 Jun 2007

Here's an example (apparent) problem: per your suggestion to "fix the WebLeftBar" so casual visitors can't "seach" we try the following (yes, the IFACCESS plugin is installed, and works in other situations):

   %IFACCESS{ type = "change" then ="
   * [[%INCLUDINGWEB%.WebSearch][ %ICON{"searchtopic"}% %MAKETEXT{"Search"}%]]
   " else = " "}%

The output looks like:

[[Sandbox.WebSearch][ <img width=

So, I'm left with the burning question: what IS the answer to your suggestion? Oh kind, generous, all-knowing Sir!-)

-- TerrillBennett - 16 Jun 2007

This is a support question for the Support web. Replace %ICON{"searchtopic"}% with %ICONURL{"searchtopic"}%. The ICON variable expands to a string with quotes, which confuses the IFACCESS parameters.

-- PeterThoeny - 17 Jun 2007

Hi, does anyone know if there's a way to put a topic contents inside another topic (just like an html iframe)?

-- KeitaMog - 16 Apr 2008

Please ask support questions in the Support web!

-- PeterThoeny - 16 Apr 2008

TWikiAdminCookBook#Rename_Main_web_to_User_web instructions are incorrect for TWiki 4.2 Should say chage $TWiki::cfg{UsersWebName} = 'Users'; in lib/LocalSite.cfg

BTW despite what it says at the top, this topic is linked from TWikiReferenceManual in my 4.2 installation

-- EliotBlennerhassett - 24 Apr 2008

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r65 < r64 < r63 < r62 < r61 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r65 - 2011-02-23 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.