-
Plugins included in the TWiki distribution do not add requirements.
| Resource | Required Server Environment * |
|---|---|
| Perl | 5.005_03 or higher (5.6.1 recommended, 5.8.x does work in most cases, but see TWiki:Codev.IssuesWithPerl5dot8) |
| Non-standard Perl modules | • Unix: Net::SMTP (or sendmail) • Windows: Net::SMTP, MIME::Base64, Digest::SHA1 • Internationalisation: Unicode::MapUTF8 (only for non-ISO-8859-1 sites using TWiki:Codev.EncodeURLsWithUTF8 with Perl 5.6 or lower) |
| RCS | 5.7 or higher (including GNU diff) Optional, but the all-Perl RCS replacement is not currently recommended for live sites - see TWiki:Codev.RcsLite |
GNU diff | GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install on PATH if not included with RCS (check version with diff -v) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
| Other external programs | fgrep, egrep |
| Cron/scheduler | • Unix: cron • Windows: cron equivalents |
| Web server | Apache 1.3 is well supported; Apache 2.0 is not recommended yet (see TWiki:Codev.IssuesWithApache2dot0). For other servers, CGI support, authentication, extended path info required; also, the register script is likely to need significant changes |
* Current documentation mainly covers Linux and Apache installations. See WindowsInstallCookbook for a Windows installation guide. See TWiki:Codev.TWikiOn for help with installation on various platforms including Unix, MacOS X, Apache mod_perl, web hosts, etc.
Plugins included in the TWiki distribution do not add requirements.
diff and grep tools if in doubt!) and TWiki:Codev/TWikiOnLinux.
NOTE: If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.
/home/httpd/twiki and unzip the TWiki distribution into this directory.
twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file httpd.conf (typcially located in /etc/httpd/) with only ExecCGI option.
twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
NOTE: The ScriptAlias must come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.
Examplehttpd.confentries:ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/" Alias /twiki/ "/home/httpd/twiki/" <Directory "/home/httpd/twiki/bin"> Options +ExecCGI SetHandler cgi-script Allow from all </Directory> <Directory "/home/httpd/twiki/pub"> Options FollowSymLinks +Includes AllowOverride None Allow from all </Directory> <Directory "/home/httpd/twiki/data"> deny from all </Directory> <Directory "/home/httpd/twiki/templates"> deny from all </Directory>
service httpd restart (or as appropriate to your flavor of UNIX or Linux).
twiki/bin directory is CGI-enabled by trying visiting it in your browser:
bin directory, http://yourdomain.com/twiki/bin/
"Forbidden. You don't have permission to access /twiki/bin/ on this server".
"Index of /twiki/bin" - recheck your httpd.conf file.
pub)
Note: Don't worry if you are not able to put the
TWiki dir: What it is: Where to copy: Example: twikistart-up pages root TWiki dir /home/smith/twiki/twiki/binCGI bin CGI-enabled dir /home/smith/twiki/bintwiki/liblibrary files same level as twiki/bin/home/smith/twiki/libtwiki/pubpublic files htdoc enabled dir /home/smith/twiki/pubtwiki/datatopic data dir secure from public access /home/smith/twiki/datatwiki/templatesweb templates dir secure from public access /home/smith/twiki/templates
twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the /twiki/bin/setlib.cfg file (done in Step 3)
/usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
.cgi extension to run. Some systems need .pl, the regular Perl extension. Rename all twiki/bin scripts if necessary.
twiki/bin/.htaccess that contains the single line SetHandler cgi-script, which tells Apache to treat all files in this directory as CGI scripts.
twiki/bin directory as executable to -rwxr-xr-x (755).
.tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
twiki with your own username
twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as www-data, or delete them all - new files will be automatically created the first time each topic is edited. You have two options to change ownership of the RCS lock user:
testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
cd twiki/data find . -name *,v -exec perl -pi~ -e '$. <= 10 && s/nobody:/www-data:/ ' {} \; *,v~ backup files which you should remove after verification: find . -name *,v~ -exec rm -f {} \;
/twiki/bin/setlib.cfg
$twikiLibPath to the absolute file path of your /twiki/lib as seen by the web server.
Attention: Do not leave it as a relative "../lib" path or Plugins might fail to initialize properly
$localPerlLibPath if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.
Attention: If you are running TWiki on Apache 2.0 on Unix you might experience cgi scripts to hang forever. This is a known Apache 2.0 bug. See details and woraround in the setlib.cfg file.
twiki/lib/TWiki.cfg, setting the variables to your needs.
$scriptSuffix variable to cgi or pl if required.
$storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
$storeTopicImpl = "RcsLite"; for the Perl based RCS
twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.
TWiki.cfg file's Internationalisation section to set the $useLocale parameter to 1. TWiki will now use the I18N parameters set in the rest of this section.
locale -a to find a suitable 'locale' for your use of TWiki. A locale that includes a dot followed by a character set is recommended, e.g. pl_PL.ISO-8859-2 for Poland. Consult your system administrator if you are not sure which locale to use.
TWiki.cfg, set the $siteLocale parameter to your chosen locale, e.g. pl_PL.ISO-8859-2 for Poland.
testenv (download the latest testenv from TWiki:Support/SupportGuidelines if possible) - this provides some diagnostics for I18N setup, and in particular checks that your locale can be used successfully.
TWiki.cfg parameter $localeRegexes to 0 - this disables some features but enables TWiki to work even if your system has locales that do not work. Then, set the $upperNational and $lowerNational parameters to the valid upper and lower case accented letters for your locale.
$useLocale set to 1 and set $localeRegexes to 0, then set $upperNational and $lowerNational - if testenv generates the lists of characters for you, your locales are working so there is no need to set $localeRegexes to 0 in this case. See the comments in TWiki.cfg for more information.
WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
WIKIWEBMASTER should be set to the email address of the TWiki administrator
SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.
WEBCOPYRIGHT messages, and other preferences.
%VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.
.htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. The comment at the top of the file explains what need to be done, basically replace !FILE_path_to_TWiki! and !URL_path_to_TWiki! with paths specific to your installation. For the details of how this file works, consult the HTTP server documentation (for Apache server: [1], [2]).
NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.
The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.
NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.
$htpasswdFormatFamily, $htpasswdEncoding and $htpasswdFilename in the TWiki.cfg file. The supported options are htpasswd:plain, htpasswd:crypt, htpasswd:sha1, htdigest:md5
.txt and .txt,v files in the twiki/data/TWiki directory.
name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
NOTE: User home topics are located in the TWiki.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!)
- See WindowsInstallSummary for a concise summary of the whole cookbook.
HOME since this is not always picked up by Cygwin
register script edits to Dec 2001 release
binutils to list of Cygwin packages, and added warning not to use Apache 2.0
SMTPMAILHOST for user registration and notification
| Component | Name, version | Comment |
|---|---|---|
| Operating System | Windows 2000 | Should also work for Windows NT |
| Web Server | Apache 1.3.27 | Windows-specific security holes fixed in this build (check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet) |
| Unix tools | Cygwin 1.3.9 | Simplest way to get a whole set of required tools |
| Perl | Cygwin perl-5.6.1-2 | Comes with Cygwin, don't use Perl 5.8.0 yet |
| RCS | Cygwin rcs-5.7-2 | Comes with Cygwin, includes a file corruption bugfix |
Major version upgrades, such as Apache 2.0 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate users created by the current TWiki user registration script (due to a feature being removed in 2.0, see TWiki:Support.FailedAuthenticationWithApache2OnWinNT). Similarly, Perl 5.8 may introduce issues due to its Unicode features and has caused problems due to a bug in CGI.pm. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki at present. For more information, see TWiki:Codev.IssuesWithApache2dot0 and TWiki:Codev.IssuesWithPerl5dot8.
TWiki.cfg, and is probably a simpler choice if you need an easy way to install mod_perl (see TWiki:Codev.ModPerl). TWiki:Codev.ActiveState Perl can be substituted without too much hassle, and in fact the same TWiki.cfg can be used for both TWiki:Codev.ActiveState and Cygwin Perl.
mod_perl, you may want to try TWiki:Codev.WindowsModPerlInstallCookbook.
$ : Cygwin DLL version is the number in 1.3.x format $ uname -r $ less c:/your-apache-dir/Announcement $ perl -v $ rcs -VIf you have an older version of any component, do yourself a favour and upgrade it as part of the install process.
nano, a very simple text editor, installed optionally during Cygwin installation. Always launch nano with the -w command-line option to turn off wrapping of long lines.
vi, a more sophisticated editor that should be familiar to most UNIX users
c:/apache almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Windows "DOS" command line shell - here, you must use double quotes around forward slashes, e.g. dir "c:/apache" will work fine.
The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.
c:/apache format, but it also provides a more Unixlike syntax, e.g. /usr/bin/rcs.exe, because some Unix tools ported onto Cygwin only support the Unix format.
When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.
httpd.conf file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.
ls, egrep, and the RCS tools that it (typically) launches with the bash shell.
If you need to use spaces in file names (not recommended), you may be able to put double quotes around the file name in the TWiki.cfg file - however, it's not clear whether all the TWiki code would work with this.
apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher
instmsi.exe) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.
c:\ as the installation directory - this actually installs Apache into c:\apache (if you specify c:\apache, it installs into c:\apache\Apache). Putting Apache into c:\Program Files is not recommended for easy editing of Apache config files from Cygwin.
apache -k restart for standalone Apache process running in another window
apache -k restart -n apache for Apache running as a Win2000 service (-n gives name of service)
apache -k stop.
Install or update now! link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist.
Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.
c:\download\cygwin-dist as the local package directory, and suitable proxy settings, then pick a local mirror site
bash
binutils
diffutils
gcc
grep
gzip
make
nano (or vim if you prefer the vi editor)
ncftp
pcre
perl (5.6.1-2 or higher, but not 5.8.0)
rcs (5.7-2 or higher)
tar
textutils
unzip
w32api
wget (optional, useful for Perl install and TWiki:Codev.ReadWriteOfflineWiki)
lynx if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5.
gcc, which is required for simple installation of Perl modules that use the C language. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).
HOME environment variable to c:\cygwin\home\YOURUSER, where YOURUSER is your userid, e.g. jsmith or administrator.
HOME (must be upper case) as the variable name, and c:\cygwin\home\YOURUSER as the value, and hit OK.
TEMP to c:\temp at this point, if you prefer this to editing the Cygwin ~/.profile file. (HOME can't be set in the ~/.profile file.)
c:\cygwin\home\YOURUSER directory
bash shell, which has command line editing features
bash will 'complete' the name. If bash beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!
rcs -V - you should see the RCS version, 5.7
perl -v - you should see cygwin mentioned in the first line, and the Perl version, 5.6.1
grep home /etc/passwd - you should see some output.
$ mkdir /twiki /c c:/twiki $ mount -b -s c:/twiki /twiki $ mount -b -s c:/ /c $ mount -b -c /cygdrive $ mount Device Directory Type Flags C:\cygwin\bin /usr/bin system binmode C:\cygwin\lib /usr/lib system binmode C:\cygwin / system binmode c:\twiki /twiki system binmode c: /c system binmode
/twiki (known as a 'mount point') to map onto c:/twiki and for that directory tree to always be in binary mode, and does the same for /c, mapping it onto c:/. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/, aka /cygdrive/z).
mount say 'binmode' under Flags
C:\cygwin directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.
/twiki/bin/view or /c/apache/Announcement - see the Cygwin documentation for more details on this.
cd /twiki
echo hi >t
cat -v t - you should see hi as the output
hi^M as output, your /twiki directory is not in binary mode
rm t
.profile file. For more information on binary vs text mode, see this User Guide section and this FAQ entry.
c:/twiki directory.
8. Install TWiki
Unzip the ZIP file under c:/twiki using WinZip, or by going into Cygwin and doing the following - you can hit the TAB key to complete filenames after you've typed the first part:
$ cd /twiki $ unzip TWiki20011201.zip
c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows environment settings.
c:\temp directory, by typing mkdir c:\temp in a DOS command line window
# Change this to point to the Apache administrator (e.g. you) ServerAdmin you@yourdomain.com # Replaces DocumentRoot "C:/apache/htdocs" DocumentRoot "C:/twiki" # Replaces <Directory "C:/apache/htdocs"> <Directory "C:/twiki">
# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory "C:/twiki/bin/">
# RD: Changed None to All in next line, to enable .htaccess
AllowOverride All
Allow From All
Options ExecCGI
SetHandler cgi-script
</Directory>
# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
# Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
# timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT
# during non-daylight-savings time (use '-5' for timezones in advance of GMT).
SetEnv TZ GMT0BST
SetEnv RCSINIT -x,v/
# Adjust TEMP and TMP for your server and create directories if necessary
SetEnv TEMP c:/temp
SetEnv TMP c:/temp
SetEnv LOGNAME system
SetEnv HOME c:/twiki
</IfModule>
2. Configure Apache (part 2)
Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation.
#
# Document types
#
<IfModule mod_mime.c>
# TWiki setup - avoid renaming scripts
AddHandler cgi-script .
...
c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:
c:/twiki format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki pathnames with Cygwin, and do report your experiences...
fgrep and egrep to grep, requiring the settings for these commands to point directly to grep (with suitable flags to provide fgrep and egrep behaviour).
# variables that need to be changed when installing on a new server:
# ==================================================================
# http://TWiki.org/ : link of TWiki icon in upper left corner :
$wikiHomeUrl = "http://yourdomain.com/bin/view";
# Host of TWiki URL : (Example "http://myhost.com:123")
$defaultUrlHost = "http://yourdomain.com";
# /cgi-bin : cgi-bin path of TWiki URL:
$scriptUrlPath = "/bin";
# ./pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath = "/pub";
# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.
# Public data directory, must match $pubUrlPath :
$pubDir = "/twiki/pub";
# Template directory :
$templateDir = "/twiki/templates";
# Data (topic files) root directory :
$dataDir = "/twiki/data";
....
# Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
# (Note: PATH environment variable is not changed if set to "")
# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.
# Unix/Linux setting:
# $safeEnvPath = "/bin:/usr/bin";
# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin. Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath = "/bin";
# If using ActiveState perl, use Windows paths instead
# $safeEnvPath = "c:/cygwin/bin";
...
# RCS directory (find out by 'which rcs') :
$rcsDir = "c:/cygwin/bin";
...
# Unix egrep command :
$egrepCmd = "/bin/grep -E";
# Unix fgrep command :
$fgrepCmd = "/bin/grep -F";
For the cookbook install using Cygwin Perl, there's no more TWiki.cfg editing to be done, so you can get onto the next section.
# NOTE: When using ActiveState Perl, you must specify # a full Windows-style pathname, using '\\' for backslashes, # for the ls, egrep and fgrep commands, because Cygwin's shell # is not used - forward slashes are OK in Windows everywhere # except in the cmd.exe shell. Drive letters are OK - e.g. # 'c:\\foo\\ls' will work. When using Cygwin perl, just # use the default '/bin/ls' type settings. # # Unix ls command : $lsCmd = "c:\\cygwin\\bin\\ls"; # Unix egrep command : $egrepCmd = "c:\\cygwin\\bin\\grep"; # Unix fgrep command : $fgrepCmd = "c:\\cygwin\\bin\\grep";
perl line, you can restore from the .backup directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes.
$ cd /twiki/bin $ ls attach geturl oops rdiff save testenv viewfile changes installpasswd passwd register search upload edit mailnotify preview rename statistics view $ mkdir .backup $ cp * .backup $ head -1 view #!/usr/bin/perl -wT $ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z] $ head -1 view #!c:/cygwin/bin/perl -wT $ ls attach geturl oops rdiff save testenv viewfile~ attach~ geturl~ oops~ rdiff~ save~ testenv~ view~ changes installpasswd passwd register search upload changes~ installpasswd~ passwd~ register~ search~ upload~ edit mailnotify preview rename statistics view edit~ mailnotify~ preview~ rename~ statistics~ viewfileIf for some reason the edit goes wrong, just type
cp .backup/* . (while within the bin directory) to restore the original distribution files. Use ls -a to see the .backup directory, and ls -a .backup to view its contents.
Optional step: you can do 'rm *~' to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this, type the command very carefully, as a space after the '*' will wipe out all files in this directory!
5. Minor changes to TWiki scripts
TWiki Dec 2001 release only - fixed in Feb 2003 release
If using the Dec 2001 release, you now need to make some minor edits to files in the c:/twiki/bin directory, using a suitable editor (remember to use nano -w filename if you prefer nano to vi - or just use the Windows PFE editor).
register script in /twiki/bin - change line 200 to read as follows (insert the MIME::Base64:: part):
return $user . ':{SHA}' . MIME::Base64::encode_base64(Digest::SHA1::sha1($passwd));
testenv, see TWiki:Codev.CookbookActivePerlTestenv
cpan, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them.
Note: if you are unable to get cpan working in your environment, don't panic; you can still install the modules manually. In this case, follow the instructions in CPAN: The Hard Way.
First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.
$ export TEMP=/c/temp $ cpanLots of questions about configuration and preferences - just hit Enter until you get to the questions about mirror sites, but answer the questions about FTP proxies etc if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files, some quite large, as part of this setup process, so be patient... NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on
ncftpget, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running cpan - this forces Net::FTP to use passive FTP, letting it get through such firewalls:
$ export FTP_PASSIVE=1If this works, add this line to your
~/.profile file for future use.
Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):
... (28) Turkey (29) Ukraine (30) United Kingdom Select your country (or several nearby countries) [] 30 (1) ftp://cpan.teleglobe.net/pub/CPAN (2) ftp://ftp.clockerz.net/pub/CPAN/ (3) ftp://ftp.demon.co.uk/pub/CPAN/ (4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/ (5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ (6) ftp://ftp.plig.org/pub/CPAN/ (7) ftp://mirror.uklinux.net/pub/CPAN/ (8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ (9) ftp://usit.shef.ac.uk/pub/packages/CPAN/ Select as many URLs as you like, put them on one line, separated by blanks [] 4 7 8 Enter another URL or RETURN to quit: [] New set of picks: ftp://ftp.flirble.org/pub/languages/perl/CPAN/ ftp://mirror.uklinux.net/pub/CPAN/ ftp://sunsite.doc.ic.ac.uk/packages/CPAN/Eventually, you'll get to the
cpan installer's shell prompt, where you need to install a few modules - the tool will do all the work for you.
make and gcc packages, which are required by the CPAN installer (gcc is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist (no need to exit the CPAN installer).
cpan shell -- CPAN exploration and modules installation (v1.59_54) cpan> install Net::SMTP May already be installed - if it is, try 'force install', since it's useful to be able to set firewall and passive FTP configuration when using Net::FTP. Make sure you answer 'Y' to the question about whether you want to configure this package. cpan> install Digest::SHA1 Lots of output about how CPAN finds, builds and installs the module - watch for any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make'). cpan> install MIME::Base64 May already be installed.
cpan doesn't work for you, perhaps because you are behind an uncooperative corporate firewall, you may have to fall back on installing modules manually. In this case, you need to read the CPAN INSTALL page and visit the CPAN search site to search for each module you require. Usually installation simply involves downloading the module distribution into a temporary directory and unpacking it (a .tar.gz or .tgz file is unpacked using tar zxvf file). Then do the following:
$ perl Makefile.PL $ make $ make test $ make installThe
make test step should not be skipped - for example, one known problem is with the Digest::SHA1 module on Windows NT, which does not pass its tests and does not work. This causes problems with password encoding. In this event you can use another encoding scheme or switch to unencoded passwords. There may be other problems on the various Windows configurations, and you can save yourself a lot of time.
testenv script doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt.
rcs -u and rcs -l, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:
$ cd /twiki/data $ : Make a backup of all files $ tar czvf all-files.tar.gz */* $ : Test edit a single file to check your typing $ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v $ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~ 5c5 < system:1.2; strict; --- > nobody:1.2; strict; $ : Now edit all the RCS files at once - use cursor-up to recall previous command $ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v $ : Check for any remaining files not edited $ grep 'strict;$' */*,v | grep -v system $ : Clean up - type this very carefully $ rm */*~~~
tar xzvf all-files.tar.gz and all your files, both .txt and .txt,v, will be back as they were before the edits.
SMTPMAILHOST in TWikiPreferences to an SMTP email host that is reachable and currently working. Otherwise you may get a confusing message from TWiki (fixed in TWiki:Codev.TWikiRelease01Feb2003) when registering new users or running mailnotify (for WebNotify), along the lines of:
Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.There are other settings to be made in TWikiPreferences, e.g. the
WIKIWEBMASTER and (probably) the SMTPSENDERHOST (normally your mail server or TWiki server). See the TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.
http://yourdomain.com/bin/testenv and check for warnings
testenv from TWiki:Codev/TWikiAlphaRelease and install it in c:/twiki/bin. (From TWiki.org, just click CVSget:bin/testenv to get this script)
view script) - click around a few pages and make sure the links are OK
rdiff script) - click on the Diffs link and on the '>' links at bottom of page
register script to create a new user entry in /twiki/data/.htpasswd (the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST was set correctly in TWikiPreferences (if it is unset it will not use Net::SMTP and will almost inevitably fail silently).
tail -30 /c/apache/logs/error_log to see last 30 errors from Apache
error_log file to see if there are any RCS errors so far
ls and grep are working
ls and grep are working
/twiki/pub directory.
error_log file again
httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt, and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into /twiki/data/debug.txt. There is also a /twiki/data/warning.txt file that contains less serious messages.
See TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g. TWiki:Codev.ChangePasswordOnWin2K).
If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set $egrepCmd and $fgrepCmd correctly, as mentioned above.
#!/bin/something). This is what has been used for this cookbook.
c:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.
mod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.
.htaccess file and c:/apache/conf/httpd.conf) always use Windows format paths, with forward slashes, e.g. c:/twiki
c:/cygwin/bin/perl
/twiki (using Cygwin Perl as per this cookbook)
c:/twiki
/twiki