.htaccess
files.
http://yoursite.com
http://yoursite.com/bin/view
http://yoursite.com/foswiki/bin/view
https://
), and access Foswiki via a proxy server, you may need to give bootstrap a "hint" that SSL is in use. Add
SSL=1
to the URL, eg: https://yoursite.com?SSL=1
. From there, bootstrap should function correctly. You only need to do this if the initial view screen displays without any
styling and the links on the page point to non-SSL http
locations.
/bin/view
and start editing!
At some point, you will want to re-visit Configuring Foswiki to enable out-going emails, create administrators and properly secure your installation.
/var/www
or /srv/www
directory) or as set by your hosting company.
wget https://sourceforge.net/projects/foswiki/files/latest/download
/path/to/foswiki
.
sudo chown -R {user}:{group} /path/to/foswikThe appropriate user/group ownership varies, depending upon the operating system and distribution:
RedHat, Fedora, CentOS, Gentoo, Mandriva | apache:apache |
debian, Ubuntu, Kubuntu | www-data:www-data |
Suse | wwwrun:www |
FreeBSD | www:www |
foswiki
directory, and execute access for all directories. Also verify that the data
and pub
directories and all the subdirectories and files beneath them allow write access for the web server user.
If for some reason the file permissions have been modified, the shell script
tools/fix_file_permissions.sh
can be used to repair the installation.
cd /path/to/foswiki sh tools/fix_file_permissions.shFor more information on the appropriate permissions to ensure security for your Foswiki data, see Foswiki:Support.SecuringYourSite.
tools/rewriteshebang.pl
script: cd /path/to/foswiki/tools perl rewriteshebang.plor for Windows users:
cd C:\path\to\foswiki\tools perl rewriteshebang.plThe script will determine the location of the Perl interpreter and will prompt to update both the bin and tools scripts in a single step. The changed files will be reported, and it is safe to rerun the script. If you get an error about perl command not found, the you need to find where your perl command is installed and include that in your command. For example:
C:\path\to\perl rewriteshebang.pl
In details:
Method 1: Use Foswiki's configuration generator (Needs root access)foswiki_httpd_conf.txt
can be found in the root of the foswiki installation.
mod_access_compat
is enabled for backwards compatibility when using Apache 2.4
.htaccess
template files included in distribution (Useful on shared hosting sites) .htaccess
files for the Foswiki root and each subdirectory are included in the root of your installation. Each file contains instructions on modifying it for your installation. For more information, see Foswiki:Support.SupplementalDocuments.
location and name of sample .htaccess file | copy sample file to the following location | tailoring required (Detailed instuctions in each file) |
---|---|---|
foswiki/root-htaccess.txt |
foswiki/.htaccess |
Optional: redirect to a default page for empty URL. |
foswiki/bin-htaccess-basic.txt |
foswiki/bin/.htaccess |
Optional: In most cases this file will "just work" without tailoring. |
foswiki/bin-htaccess-advanced.txt |
foswiki/bin/.htaccess |
Yes. Use this file for configuring Apache login, LDAP authentication and other advanced configurations. Must find/replace all instances of {DataDir} , {DefaultUrlHost} and {ScriptUrlPath} with valid information. The setting SetHandler cgi-script is critical to make sure that scripts in the bin directory will be executed by Apache. |
foswiki/pub-htaccess.txt |
foswiki/pub/.htaccess |
Optional: - Uncomment and set correct URL path on the ErrorDocument statement for friendly handling of file-not-found errors. |
foswiki/subdir-htaccess.txt |
foswiki/<subdir>/.htaccess Copy to all other subdirectories below foswiki , includingdata , lib , locale , templates , tools , working .All directories except for bin and pub addressed above. |
No |
bin
and pub
. All three of the approaches described above (Foswiki:Support.ApacheConfigGenerator, the sample foswiki_httpd_conf.txt
file included in the distribution, or .htaccess
files) should provide for this but it should be confirmed by using web browser to confirm that direct access to the other directories is blocked.
pub
directory. Again, the three approaches described above all provide for this. However, different script execution mechanisms are disabled in different ways so refer see your web server configuration and documentation for more details.
mod_access_compat
is enabled for backwards compatibility when using Apache 2.4, or use the Foswiki:Support.ApacheConfigGenerator config generator.
configure
script no longer needs any special protection within the Apache configuration.http://yoursite.com/foswiki/bin/view
http://yoursite.com/bin/view
http://yoursite.com
bin/configure
URL or Foswiki will not correctly detect the URL configuration).
{PermittedRedirectHostUrls}
. Example: if {DefaultUrlHost}
is set to https://wiki.company.com
, an example {PermittedRedirectHostUrls}
might contain: https://company.com, http://111.222.123.234
Outgoing e-mail is required for Foswiki to send registration confirmations, notifications of changes, password reset requests, etc.
Mail
tab in left bar of confgiure and fill out the following parameters: {WebMasterEmail}
should be set to a valid e-mail address. This will be the From: ID used to send Foswiki Emails and will also appear on webmaster mailto: links. {SMTP}{MAILHOST}
should be set to your e-mail server hostame: ex: smtp.gmail.com
{SMTP}{Username}
and {SMTP}{Password}
. These are used so that Foswiki can sign into the e-mail server for purposes of sending e-mail.
{WebMasterEmail}
field This will verify if the configuration is correct and able to send mail. If e-mail is enabled, but not functional, you will be unable to register users.
Click the Save button in the upper right corner of the configuration page.
Refer back to any page in your installation (such as the "AdminGroup" page you were at in the previous step). The login section at the top of the left-hand menu should show that you are still be logged in as a temporary Admin user. Click on the "Log Out" link to exit that user.
You now have set up your Foswiki installation! At this point you can start creating and editing pages. See InstallationGuidePart2 to proceed with further tailoring your site.
In order to keep your user, group, and site configuration information separate from the actual content of your site, it is recommended that you create a new web in which your site's pages will reside. See ManagingWebs for more information on Wiki webs and how to create one.If you are having problems with your installation, try the following:
configure
script and ensure you have resolved all errors and are satisfied that you understand any warnings. cd /path/to/foswiki perl tools/dependencies
Foswiki is written in Perl 5, which is supported on Microsoft Windows as well as Unix and Unix-like systems (including Linux and OSX). On Unix-like systems, it uses a number of shell commands. It should be able to run out-of-the-box on any server platform that meets the following requirements.
Resource | Required Server Environment |
---|---|
Perl | 5.8.8 or higher. A minimum of perl 5.12 is recommended. |
External programs | GNU diff 2.7 or higher, fgrep , and egrep (not required on Windows) |
Web server | Apache, Nginx and Lighttpd are all well supported; Apache sample configs are provided. For information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms. |
configure
script is run, but start from your expected default "view" URL, so that Foswiki can figure out your URL scheme.
Prior versions of Foswiki shipped with the important CPAN modules. Foswiki 2.0 does not, and you must ensure that the perl dependencies listed below are installed before attempting to use Foswiki. For a detailed report, PerlDependencyReport (admin access only!) or the shell script tools/dependencies
.
If you are unable to install CPAN modules, see Foswiki:Extensions.CpanContrib. Install this extension into your Foswiki installation directory if you cannot install Perl modules otherwise.
You can check the dependencies before Foswiki is fully operational with the following command. It will list all potentially missing dependencies. Not all listed dependences are required on all installations, Refer to the usage message that accompanies each missing dependency in the report.
cd /path/to/foswiki perl tools/dependencies
apt-get install apache2 rcs
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | libalgorithm-diff-perl |
|
Archive::Tar | libarchive-tar-perl |
|
Authen::SASL | libauthen-sasl-perl |
|
CGI | libcgi-pm-perl |
|
CGI::Session | libcgi-session-perl |
|
Crypt::PasswdMD5 | libcrypt-passwdmd5-perl |
|
Digest::SHA | libdigest-sha-perl |
*First shipped in perl 5.9.3 |
Email::Address::XS | libemail-address-xs-perl |
|
Email::MIME | libemail-mime-perl |
|
Encode | libencode-perl |
|
Error | liberror-perl |
|
File::Copy::Recursive | libfile-copy-recursive-perl |
|
HTML::Parser | libhtml-parser-perl |
|
HTML::Tree | libhtml-tree-perl |
|
IO::Socket::IP | libio-socket-ip-perl |
First shipped perl 5.19.8 |
IO::Socket::SSL | libio-socket-ssl-perl |
|
JSON | libjson-perl |
|
Locale::Codes | liblocale-codes-perl |
|
Locale::Maketext | liblocale-maketext-perl |
|
Locale::Maketext::Lexicon | liblocale-maketext-lexicon-perl |
Optional, needed for internationalization |
Locale::Msgfmt | liblocale-msgfmt-perl |
Optional, needed for internationalization |
LWP | libwww-perl |
|
LWP::Protocol::https | liblwp-protocol-https-perl |
|
URI | liburi-perl |
|
version | libversion-perl |
Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
apt-get install
libalgorithm-diff-perl
libarchive-tar-perl
libauthen-sasl-perl
libcgi-pm-perl
libcgi-session-perl
libcrypt-passwdmd5-perl
libdigest-sha-perl
libemail-address-xs-perl
libemail-mime-perl
libencode-perl
liberror-perl
libfile-copy-recursive-perl
libhtml-parser-perl
libhtml-tree-perl
libio-socket-ip-perl
libio-socket-ssl-perl
libjson-perl
liblocale-codes-perl
liblocale-maketext-perl
liblocale-maketext-lexicon-perl
liblocale-msgfmt-perl
libwww-perl
liblwp-protocol-https-perl
liburi-perl
libversion-perl
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | libapache2-mod-perl2 |
Required if using Apache 2 and mod_perl |
Apache2::Request | libapache2-request-perl |
Required if using Apache 2 and mod_perl |
DBI | libdbi-perl |
Used for the Foswiki Page cache |
DBD::mysql | libdbd-mysql-perl |
Used for MySQL based Page Cache |
DBD::Pg | libdbd-pg-perl |
Used for PostgreSQL based Page Cache |
DBD::SQLite | libdbd-sqlite3-perl |
Used for SQLite based Page Cache |
FCGI | libfcgi-perl |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | libfcgi-procmanager-perl |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | libcrypt-smime-perl |
Optional, used for S/MIME email signing |
Crypt::X509 | libcrypt-x509-perl |
Optional, used for S/MIME email signing |
Convert::PEM | libconvert-pem-perl |
Optional, used for S/MIME email signing |
chown -R www-data:www-data /path/to/foswiki
a2enmod rewrite
a2enmod cgi
OR a2enmod cgid
a2enmod access_compat
Install apache2, rcs, and perl-CPAN
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | perl-Algorithm-Diff |
|
Archive::Tar | perl-Archive-Tar |
*First shipped in perl 5.9.3 |
Authen::SASL | perl-Authen-SASL |
|
CGI | perl-CGI |
|
CGI::Session | perl-CGI-Session |
|
Crypt::PasswdMD5 | perl-Crypt-PasswdMD5 |
|
Digest::SHA | perl-Digest-SHA |
*First shipped in perl 5.9.3 |
Email::Address::XS | perl-Email-Address-XS |
|
Email::MIME | perl-Email-MIME |
|
Encode | perl-Encode |
|
Error | perl-Error |
|
File::Copy::Recursive | perl-File-Copy-Recursive |
|
HTML::Parser | perl-HTML-Parser |
|
HTML::Tree | perl-HTML-Tree |
|
IO::Socket::IP | perl-IO-Socket-IP |
First shipped perl 5.19.8 |
IO::Socket::SSL | perl-IO-Socket-SSL |
|
JSON | perl-JSON |
|
Locale::Language | perl-Locale-Codes |
|
Locale::Maketext | perl-Locale-Maketext |
|
Locale::Maketext::Lexicon | perl-Locale-Maketext-Lexicon |
Optional, needed for internationalization ** |
Locale::Msgfmt | perl-Locale-Msgfmt |
Optional, needed for internationalization ** |
LWP | perl-libwww-perl |
|
LWP::Protocol::https | perl-LWP-Protocol-https |
|
URI | perl-URI |
|
version | perl-version |
Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
Locale::Maketext::Lexicon
and Locale::Msgfmt
are not available on
Centos. Install using CPAN if Internationalization is required.
First add the appropriate perl module repository, and then install the packages.
yum install -y epel-release
yum install
perl-Algorithm-Diff
perl-Archive-Tar
perl-Authen-SASL
perl-CGI
perl-CGI-Session
perl-Crypt-PasswdMD5
perl-Digest-SHA
perl-Email-Address-XS
perl-Email-MIME
perl-Encode
perl-Error
perl-File-Copy-Recursive
perl-HTML-Parser
perl-HTML-Tree
perl-IO-Socket-IP
perl-IO-Socket-SSL
perl-JSON
perl-Locale-Codes
perl-Locale-Maketext
perl-Locale-Maketext-Lexicon
perl-Locale-Msgfmt
perl-libwww-perl
perl-LWP-Protocol-https
perl-URI
perl-version
zypper ar -f -n perl-modules http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_13.1 perl-modules
zypper install
perl-Algorithm-Diff
perl-Archive-Tar
perl-Authen-SASL
perl-CGI
perl-CGI-Session
perl-Crypt-PasswdMD5
perl-Digest-SHA
perl-Email-Address-XS
perl-Email-MIME
perl-Encode
perl-Error
perl-File-Copy-Recursive
perl-HTML-Parser
perl-HTML-Tree
perl-IO-Socket-IP
perl-IO-Socket-SSL
perl-JSON
perl-Locale-Codes
perl-Locale-Maketext
perl-Locale-Maketext-Lexicon
perl-Locale-Msgfmt
perl-libwww-perl
perl-LWP-Protocol-https
perl-URI
perl-version
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | mod_perl |
Required if using Apache2 and mod_perl |
Apache2::Request | perl-libapreq2 |
Required if using Apache 2 and mod_perl |
DBI | perl-DBI |
Used for the Foswiki Page cache |
DBD::mysql | perl-DBD-mysql |
Used for MySQL based Page Cache |
DBD::Pg | perl-DBD-Pg |
Used for PostgreSQL based Page Cache |
DBD::SQLite | perl-DBD-SQLite |
Used for SQLite based Page Cache |
FCGI | perl-FCGI |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | perl-FCGI-ProcManager |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | perl-Crypt-SMIME |
Optional, used for S/MIME email signing (Not available in default repositories) |
Crypt::X509 | perl-Crypt-X509 |
Optional, used for S/MIME email signing |
Convert::PEM | perl-Convert-PEM |
Optional, used for S/MIME email signing |
chown -R wwwrun:www /path/to/foswiki
www-servers/apache
, dev-vcs/rcs
, and dev-lang/perl
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | dev-perl/Algorithm-Diff |
|
Archive::Tar | perl-Archive-Tar |
*First shipped in perl 5.9.3 |
Authen::SASL | dev-perl/Authen-SASL |
Optional, needed for authenticated SMTP |
CGI | dev-perl/CGI |
|
CGI::Session | dev-perl/CGI-Session |
|
Crypt::PasswdMD5 | dev-perl/Crypt-PasswdMD5 |
|
Digest::SHA | Included with perl | |
Email::Address::XS | dev-perl/Email-Address-XS |
|
Email::MIME | dev-perl/Email-MIME |
|
Error | dev-perl/Error |
|
Encode | Included with perl | |
File::Copy::Recursive | dev-perl/File-Copy-Recursive |
|
HTML::Parser | dev-perl/HTML-Parser |
|
HTML::Tree | dev-perl/HTML-Tree |
|
IO::Socket::IP | Ebuild not avaiable. Install with g-cpan if IPv6 is needed. | |
IO::Socket::SSL | dev-perl/IO-Socket-SSL |
Optional, support encrypted email connection: STARTTLS or SSL |
JSON | dev-perl/JSON |
|
Locale::Maketext | Included with perl | |
Locale::Maketext::Lexicon | dev-perl/Locale-Maketext-Lexicon |
Optional, needed for internationalization |
Locale::Msgfmt | dev-perl/Locale-Msgfmt |
Optional, needed for internationalization |
LWP | dev-perl/libwww-perl |
|
LWP::Protocol::https | dev-perl/LWP-Protocol-https |
|
URI | dev-perl/URI |
|
version | Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
emerge
dev-perl/Algorithm-Diff
perl-Archive-Tar
dev-perl/Authen-SASL
dev-perl/CGI
dev-perl/CGI-Session
dev-perl/Crypt-PasswdMD5
dev-perl/Email-Address-XS
dev-perl/Email-MIME
dev-perl/Error
dev-perl/File-Copy-Recursive
dev-perl/HTML-Parser
dev-perl/HTML-Tree
dev-perl/IO-Socket-SSL
dev-perl/JSON
dev-perl/Locale-Maketext-Lexicon
dev-perl/Locale-Msgfmt
dev-perl/libwww-perl
dev-perl/LWP-Protocol-https
dev-perl/URI
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | www-apache/mod_perl |
Required if using Apache 2 and mod_perl |
Apache2::Request | libapache2-request-perl |
Required if using Apache 2 and mod_perl |
DBI | dev-perl/DBI |
Optional - Used for the Foswiki Page cache |
DBD::mysql | dev-perl/DBD-mysql |
Optional - Used for MySQL based Page Cache |
DBD::Pg | dev-perl/DBD-Pg |
Optional - Used for PostgreSQL based Page Cache |
DBD::SQLite | dev-perl/DBD-SQLite |
Optional - Used for SQLite based Page Cache |
FCGI | dev-perl/FCGI |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | dev-perl/FCGI-ProcManager |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | dev-perl/Crypt-SMIME |
Optional, used for S/MIME email signing |
Crypt::X509 | dev-perl/Crypt-X509 |
Optional, used for S/MIME email signing |
Convert::PEM | dev-perl/convert-pem |
Optional, used for S/MIME email signing |
chown -R apache:apache /var/www/path-to-foswiki
apache24
, rcs
, and perl5
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | p5-Algorithm-Diff |
|
Archive::Tar | p5-Archive-Tar |
|
Authen::SASL | p5-Authen-SASL |
|
CGI | p5-CGI |
|
CGI::Session | p5-CGI-Session |
|
Crypt::PasswdMD5 | p5-Crypt-PasswdMD5 |
|
Digest::SHA | p5-Digest-SHA |
*First shipped in perl 5.9.3 |
Email::Address::XS | p5-Email-Address-XS |
|
Email::MIME | p5-Email-MIME |
|
Encode | p5-Encode |
|
Error | p5-Error |
|
File::Copy::Recursive | p5-File-Copy-Recursive |
|
HTML::Parser | p5-HTML-Parser |
|
HTML::Tree | p5-HTML-Tree |
|
IO::Socket::IP | p5-IO-Socket-IP |
First shipped perl 5.19.8 |
IO::Socket::SSL | p5-IO-Socket-SSL |
|
JSON | p5-JSON |
|
Locale::Maketext | p5-Locale-Maketext |
|
Locale::Maketext::Lexicon | p5-Locale-Maketext-Lexicon |
Optional, needed for internationalization |
Locale::Msgfmt | p5-Locale-Msgfmt |
Optional, needed for internationalization |
LWP | p5-libwww |
|
LWP::Protocol::https | p5-LWP-Protocol-https |
|
URI | p5-URI |
|
version | p5-version |
Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
After expanding the Foswiki archive, change the ownership of the files:pkg install
p5-Algorithm-Diff
p5-Archive-Tar
p5-Authen-SASL
p5-CGI
p5-CGI-Session
p5-Crypt-PasswdMD5
p5-Digest-SHA
p5-Email-Address-XS
p5-Email-MIME
p5-Encode
p5-Error
p5-File-Copy-Recursive
p5-HTML-Parser
p5-HTML-Tree
p5-IO-Socket-IP
p5-IO-Socket-SSL
p5-JSON
p5-Locale-Maketext
p5-Locale-Maketext-Lexicon
p5-Locale-Msgfmt
p5-libwww
p5-LWP-Protocol-https
p5-URI
p5-version
chown -R www:wwwadmin /var/www/path-to-foswiki
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | ap24-mod_perl2 |
Required if using Apache 2 and mod_perl |
Apache2::Request | libapreq2 |
Required if using Apache 2 and mod_perl |
BSD-Resource | p5-BSD-Resource |
Optional - used for FCGI process handler resource limits |
DBI | p5-DBI |
Optional - Used for the Foswiki Page cache |
DBD::mysql | p5-DBD-mysql |
Optional - Used for MySQL based Page Cache |
DBD::Pg | p5-DBD-Pg |
Optional - Used for PostgreSQL based Page Cache |
DBD::SQLite | p5-DBD-SQLite |
Optional - Used for SQLite based Page Cache |
FCGI | p5-FCGI |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | p5-FCGI-ProcManager |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | p5-Crypt-SMIME |
Optional, used for S/MIME email signing |
Crypt::X509 | p5-Crypt-X509 |
Optional, used for S/MIME email signing |
Convert::PEM | p5-Convert-PEM |
Optional, used for S/MIME email signing |
cpanm
, aka App::cpanminus
. On most unix* systems, cpanminus
can bootstrap itself using curl or wget.
If run as root, the modules will be installed in the System perl. Otherwise they are installed into the users local environment.
Perl Module | Notes |
---|---|
Algorithm::Diff | |
Archive::Tar | *First shipped in perl 5.9.3 |
Authen::SASL | Optional, needed for authenticated SMTP |
CGI | |
CGI::Session | |
Crypt::PasswdMD5 | |
Digest::SHA | Included with perl |
Error | |
Email::Address::XS | |
Email::MIME | |
Encode | |
File::Copy::Recursive | |
HTML::Parser | |
HTML::Tree | |
IO::Socket::IP | |
IO::Socket::SSL | Optional, support encrypted email connection: STARTTLS or SSL |
JSON | |
Locale::Maketext | |
Locale::Maketext::Lexicon | Optional, needed for internationalization |
Locale::Msgfmt | Optional, needed for internationalization |
LWP | |
LWP::Protocol::https | |
URI | |
version | Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
cpanm
curl -L http://cpanmin.us | perl - App::cpanminus (optional - install cpanminus if not available )
cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 Digest::SHA Error Email::Address::XS Email::MIME Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext Locale::Maketext::Lexicon Locale::Msgfmt LWP LWP::Protocol::https URI version
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
Apache2::Request | Required if using Apache 2 and mod_perl | |
DBI | Optional - Used for the Foswiki Page cache | |
DBD::mysql | Optional - Used for MySQL based Page Cache | |
DBD::Pg | Optional - Used for PostgreSQL based Page Cache | |
DBD::SQLite | Optional - Used for SQLite based Page Cache | |
FCGI | Optional, needed for fastcgi / fcgi apache modules | |
FCGI::ProcManager | Optional, needed for fastcgi / fcgi process management on nginx | |
Crypt::SMIME | Optional, used for S/MIME email signing | |
Crypt::X509 | Optional, used for S/MIME email signing | |
Convert::PEM | Optional, used for S/MIME email signing | |
Locale::Language | Optional, Locale::Language will be removed from the Perl core distribution in 5.28. |
cpanminus
"-l"
option to cpanm, and add the lib path to bin/LocalLib.cfg
. The dependencies will be installed under the specified location, in the lib/perl5
subdirectory.
Example: User "foswiki" logs in and installs the libraries locally under the foswikideps directory:
cpanm -l foswikideps Algorithm::Diff Archive::Tar ... (install libraries into =/home/foswiki/foswikideps=)
/path/to/foswiki/bin/LocalLib.txt
is then edited, and the commented line is modified:
# @localPerlLibPath = ( '/path/to/dir', '/path/to/another/dir', ); @localPerlLibPath = ( '/home/foswiki/foswikideps/lib/perl5', );Foswiki will now run using the libraries installed by cpanm.
CSS and Javascript are used in most skins. Some skins will require more recent releases of browsers. The default (Pattern) skin is tested on IE 6+, Safari, Chrome and Firefox.
You can easily select a balance of browser capability versus look and feel. Try the installed skins at System.SkinBrowser and more at Foswiki:Extensions.SkinPackage.pub
directory.)
lib
directory at the same level as the bin
directory. You can create this directory elsewhere and configure the bin/setlib.cfg
file. Foswiki dir: | What it is: | Where to copy: | Example: |
---|---|---|---|
foswiki | start-up pages | root Foswiki dir | /home/smith/public_html/foswiki/ |
foswiki/bin | CGI bin | CGI-enabled dir | /home/smith/public_html/foswiki/bin |
foswiki/lib | library files | same level as bin | /home/smith/public_html/foswiki/lib |
foswiki/locale | language files | dir secure from public access | /home/smith/public_html/foswiki/locale |
foswiki/pub | public files | htdoc enabled dir | /home/smith/public_html/foswiki/pub |
foswiki/data | topic data | dir secure from public access | /home/smith/public_html/foswiki/data |
foswiki/templates | web templates | dir secure from public access | /home/smith/public_html/foswiki/templates |
foswiki/tools | Foswiki utlilities | dir secure from public access | /home/smith/public_html/foswiki/tools |
foswiki/working | Temporary and internal files | dir secure from public access | /home/smith/public_html/foswiki/working |
Administrators have read and write access to any topic, regardless of any access controls that have been applied to the topic or its web. Administrators also have access to configure unless further restricted.
The default setup in Foswiki is that members of Main.AdminGroup have administrator privileges. Any member of the Main.AdminGroup can add subsequent members to that group.
To more easily debug access control issues, you may want to have a regular Foswiki user account for daily use, and a special one that belongs to theAdminGroup
that you use only for administering your Foswiki site. See System.AccessControls for more information on access controls and user groups.
ALLOWTOPICCHANGE
rights on the
AdminGroup. They can then use a button on the AdminGroup page to join or leave the group at will.
bin/configure
{FeatureAccess}{Configure}
to a list of WikiNames that will be allowed access to configure.
{Password}
field to a hashed ApacheMD5
encoded password.
You must at least do one of the above before closing your browser or logging out from the temporary admin authority established during bootstrap. Once you close your browser, you have to have a usable id to run configure or you'll need to add a super-user admin login using the command line.
admin
and a password set in the configuration. Foswiki 2.0 no longer enables the internal admin by default. bin/configure
interface: The password can be set in configure, in the "Security and Authentication" → "Passwords" tab. Enter the password in plain text. It will be automatically hashed when saved, and cannot be recovered.
tools/configure -save -set {Password}='adminpass'
LocalSite.cfg
: Follow these steps: ( Caution: This procedure only works for plain ascii passwords, it does not handle international characters.) htpasswd
tool: (replacing {password}
with your password)htpasswd -bn admin {password}
admin:
ex: $apr1$Oc.PLq8V$wslABA3mWXfYT/wH0Hsom0
)
LocalSite.cfg
for $Foswiki::cfg{Password}
, Replace the existing line, or if not found, insert a new line in the file, as shown:$Foswiki::cfg{Password} = '{password hash}';
mod_auth_ldap
or mod_auth_mysql
. However, as your browser is caching your login, you must restart the browser to log out.
Note that the password databases for both of these authentication mechanisms are compatible, so you can switch between them at a later date.
Template Login asks for a username (or optionally e-mail address) and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out. Client Sessions are used to remember users. Users can choose to have their session remembered so they will automatically be logged in the next time they start their browser.
Login
, Password
and user mapping
options.configure
, Security And Authentication
tab Login
tab on the Security and Authentication
panel. Select the Foswiki::LoginManager::TemplateLogin
login manager.
Passwords
tab. Select the appropriate PasswordManager
for your system - the default is Foswiki::Users::HtPasswdUser
. {TemplateLogin}{PreventBrowserRememberingPassword}
that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.{TemplateLogin}{AllowLoginUsingEmailAddress}
that you can set to allow users to login using their password system registered e-mail addresses.With Apache Login enabled, when Foswiki needs to authenticate the user, the standard HTTP authentication mechanism is used: the browser itself will prompt for a user name and password.
The rest of this section describes Webserver Login using the Apache web server, but the same process is applicable to other webserver implementations as well (though you may require a customised version of the ApacheLogin module to do it).
The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such asmod_auth_ldap
or mod_auth_mysql
you can just plug in to them directly.
The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.
Foswiki maps theREMOTE_USER
that was used to log in to the webserver to a WikiName using the table in Main.WikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver username is used for their signature) or register (in which case that username is mapped to their WikiName).
The same private .htpasswd
file used in Foswiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.
htpasswd
program to modify .htpasswd
files generated by Foswiki! htpasswd
wipes out e-mail addresses that Foswiki saves in the info fields of this file.
Apache Login is required for Apache-based login methods such as mod_ldap
You can use any Apache authentication module that sets the REMOTE_USER
environment variable.
To set up Apache Login, perform the following steps:
Security and Authentication
pane on the Login
tab in configure
: Foswiki::LoginManager::ApacheLogin
for {LoginManager}
.
Foswiki::Users::HtPasswdUser
for {PasswordManager}
.
Foswiki::Users::TopicUserMapping
for {UserMappingManager}
.
foswiki/bin-htaccess-advanced.txt
file to set the following Apache directives on the bin
scripts:(This example is for Apache 2.2, there are changes required if using Apache 2.4) AuthType Basic <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|.*auth).*"> require valid-user </FilesMatch>You can also refer to the sample
foswiki_httpd_conf.txt
and bin-htaccess-advanced.txt
files to see how the appropriate Apache directives are specified.
Mail and Proxies
, Email Test
tab in configure
and verify that Foswiki can successfully send e-mail.
HtPasswdUser
(the default), check the .htpasswd
file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName}
is correct (under Security and Authentication
on the Password
tab in configure
), and that the webserver user has write permission.
configure
page) -CAS
option so that all prompted input is properly encoded.
$ perl -CAS tools/configure -save
$ tools/configure -save LocalSite.cfg load failed AUTOCONFIG: Found Bin dir: /var/www/foswiki/distro/core/tools, Script name: configure using FindBin AUTOCONFIG: PubDir = /var/www/foswiki/distro/core/pub AUTOCONFIG: DataDir = /var/www/foswiki/distro/core/data AUTOCONFIG: WorkingDir = /var/www/foswiki/distro/core/working AUTOCONFIG: ToolsDir = /var/www/foswiki/distro/core/tools AUTOCONFIG: TemplateDir = /var/www/foswiki/distro/core/templates AUTOCONFIG: LocalesDir = /var/www/foswiki/distro/core/locale AUTOCONFIG: ScriptDir = /var/www/foswiki/distro/core/bin AUTOCONFIG: Unable to use PlainFileStore: ,v files were found in data or pub, which indicates this installation is already configured for RCS e.g. /var/www/foswiki/distro/core/data/WFWeb/WebChanges.txt,v AUTOCONFIG: Store configured for RcsLite AUTOCONFIG: {Store}{SearchAlgorithm} set to Forking AUTOCONFIG: Detected OS UNIX: DetailedOS: linux ** Enter values for critical configuration items. ** type a new value or hit return to accept the value in brackets. This is the root of all Foswiki URLs. For example, =http://myhost.com:123= (do not include the trailing slash.) {DefaultUrlHost} (http://localhost): http://myhost.com This is the 'cgi-bin' part of URLs used to access the Foswiki bin directory. For example =/foswiki/bin=. See [[https://foswiki.org/Support/ShorterUrlCookbook][ShorterUrlCookbook]] for more information on setting up Foswiki to use shorter script URLs. {ScriptUrlPath} (/foswiki/bin): ...It can also be run in a non-interactive mode, for use in automated deployment systems.
tools/configure -save -noprompt tools/configure -save -set {DefaultUrlHost}='http://mysite.com' tools/configure -save -set {ScriptUrlPath}='/bin' tools/configure -save -set {ScriptUrlPaths}{view}='' tools/configure -save -set {PubUrlPath}='/pub' perl -CA tools/configure -save -set {Password}='ÄdmînPäss'
Any configuration keys may be set using this tool.
To run a wizard, for example autoconfiguration of email:tools/configure -save -set {WebMasterEmail}='user@email.com' tools/configure -save -set {SMTP}{MAILHOST}='smtpserver.email.com' tools/configure -save -set {SMTP}{Username}='userid' tools/configure -save -set {SMTP}{Password}='password' tools/configure -save -wizard AutoConfigureEmail -method autoconfigureAnd the configuration can then be checked, with optional verbose output: (Without -verbose, only errors and warnings are reported.)
tools/configure -check -verboseFile system permissions can also be checked for any of
{DataDir}
, {LocalesDir}
, {PubDir}
, {ScriptDir}
, {TemplateDir}
, {ToolsDir}
and {WorkingDir}
, for ex:
tools/configure -check {DataDir} -method validate_permissionsConfiguration settings can be searched and queried as well:
tools/configure -search Umask tools/configure -getcfg {Store}
TWikiCompatibilityPlugin
. This plugin enables most TWiki extensions to work with Foswiki, without modifications. It also maps requests for legacy TWiki web topics to their Foswiki equivalents, as defined in Foswiki:Development.TopicNameMappingTable. The TWIKIWEB
and MAINWEB
TWiki variables are also mapped to the new Foswiki macros SYSTEMWEB
and USERSWEB
.
If you are not upgrading an existing TWiki installation and do not plan to install plugins from the TWiki web site, it is recommended that you disable the TWikiCompatibilityPlugin in the Plugins Section on the configure
page.
If a plugin exists both in a TWiki version and a Foswiki version, it is strongly recommended that you use the Foswiki version, as this is coded to work optimally with Foswiki. As part of the Foswiki project, the Foswiki community is evaluating all of the extensions that are available for TWiki, and porting them over to the Foswiki name space. Many of them are being enhanced through the removal of bugs and security vulnerabilities, resulting in better, more functional extensions for Foswiki.
TWiki is a registered trademark of Peter Thoeny. Related Topics: InstallationGuidePart2, AdminDocumentationCategory, Foswiki:Support.SupplementalDocuments