Install TWiki on the OpenSUSE Linux Development Server

Linux No Comments

opensuseWhen you’re working in a small engineering team, one of the best tools for collaboration is a wiki. After looking at TikiWiki, MediaWiki, and TWiki, I decided to use TWiki. TWiki had the most sophisticated syntax for formatting a page. TWiki’s syntax trumped the downsides of using Perl and files, instead of PHP and MySQL which are used by TikiWiki and MediaWiki.

Below are notes I took when installing and securing TWiki on our OpenSUSE Linux development server.

  1. Perl 5.12 comes pre-installed with OpenSUSE 11.3. Double-check that it is installed properly by running:
    perl -version
  2. Browse to http://twiki.org/. Click on the “Download TWiki-5.0.1” button to the right. Input the info requested in the download form on the right half and click on the Download button. You will download a zip archive named “TWiki-5.0.1.zip”.
  3. Put the archive file onto your Linux server. As root user, unzip it to a “twiki” directory under the secure web rot directory “htdocs-ssl” and adjust the permissions so the Apache user can access it:
    unzip TWiki-5.0.1.zip -d /srv/www/htdocs-ssl/twiki
    chown -R wwwrun:www /srv/www/htdocs-ssl/twiki
  4. Start configuring TWiki by creating a “LocalLib.cfg” file:
    cd /srv/www/htdocs-ssl/twiki/bin
    cp LocalLib.cfg.txt LocalLib.cfg

    Edit the resulting “LocalLib.cfg” file and update the variable “$twikiLibPath” to be the correct path:

    $twikiLibPath = "/srv/www/htdocs-ssl/twiki/lib"
  5. Configure Apache by creating a “/etc/apache2/twiki.conf” file with the content below. I generated it using TWiki:TWiki.ApacheConfigGenerator and cleaned it up. (For security reasons, we are putting twiki.conf under “/etc/apache2” instead of “/etc/apache2/conf” to prevent the TWiki Directory directives from being applicable to non-secure HTTP access.)
    # Prevent TWiki from including its own topics as URLs (used by DOS attacks).
    BrowserMatchNoCase ^$ blockAccess

    # ScriptAlias defines bin as a directory where CGI scripts are allowed.
    ScriptAlias /twiki/bin "/srv/www/htdocs-ssl/twiki/bin"

    # Alias defines pub directory as the root of file attachments.
    Alias /twiki/pub "/srv/www/htdocs-ssl/twiki/pub"

    # Secure file attachments by using viewfile which enforces permission
    RewriteEngine on
    RewriteCond %{REQUEST_URI} !^/+twiki/+pub/+(TWiki|Sandbox)/+.+
    RewriteRule ^/+twiki/+pub/+(.*)$  /twiki/bin/viewfile/$1 [L,PT]

    # Block access to typical spam related attachments
    SetEnvIf Request_URI "twiki/pub/.*\.[hH][tT][mM][lL]?$" blockAccess
    SetEnvIf Request_URI "twiki/pub/TWiki/.*\.[hH][tT][mM][lL]?$" !blockAccess

    # Allow everyone to run perl scripts from the bin directory.
    <Directory "/srv/www/htdocs-ssl/twiki/bin">
      AllowOverride None
      Order Allow,Deny
      Allow from all
      Deny from env=blockAccess

      Options ExecCGI FollowSymLinks
      SetHandler cgi-script

      # Password file for TWiki users
      AuthUserFile /srv/www/htdocs-ssl/twiki/data/.htpasswd
      AuthName 'Enter your login name:'
      AuthType Basic

      # File to return on access control error (e.g. wrong password)
      ErrorDocument 401 /twiki/bin/view/TWiki/TWikiRegistration

      # Limit access to configure script to localhost since it contains sensitive info.
      <FilesMatch "^(configure)$">
         SetHandler cgi-script
         Order Deny,Allow
         Deny from all
         Allow from localhost
      </FilesMatch>
    </Directory>

    # Allow access to the pub directory for attachments, CSS stylesheets and icons.
    <Directory "/srv/www/htdocs-ssl/twiki/pub">
      Options None
      AllowOverride None
      Order Allow,Deny
      Allow from all
      Deny from env=blockAccess

      # Disable execusion of PHP scripts
      php_admin_flag engine off

      # This line will redefine the mime type for the most common types of scripts
      AddType text/plain .shtml .php .php3 .phtml .phtm .pl .py .cgi
    </Directory>

    # With exception of bin and pub directories, prevent access to everything else.
    <Directory "/srv/www/htdocs-ssl/twiki/">
      Deny from all
    </Directory>

    # Either of this will redirect root / to twiki/bin/view
    #RewriteRule ^/$ /twiki/bin/view
    #RedirectMatch ^/$ /twiki/bin/view

    If you can’t run a browser under localhost, then make sure to comment out the “<FilesMatch “^(configure)$”>” block above so you can run the configure script remotely. If you want to redirect from the root URL to TWiki, just uncomment either “RewriteRule” or “RedirectMatch” at the end; don’t uncomment both because I’m not sure what would happen.

  6. To allow access to the TWiki only from SSL/HTTPS, we will include the twiki.conf into the SSL virtual host configuration. Edit the “/etc/apache2/vhost.d/your_vhost-ssl.conf” file (which you created in this post) and add the following Include directive anywhere inside the “<VirtualHost>” block:
    <VirtualHost _default_:443>
         ...
         Include /etc/apache2/twiki.conf
         ...
    </VirtualHost>
  7. The twiki.conf uses the mod_redirect module which we will need to configure Apache to load on startup. Good thing we have to restart Apache for the Twiki.conf to take effect also.
    a2enmod redirect
    rcapache2 restart
  8. Run the Twiki configure script by browsing to “https://localhost/twiki/bin/configure” or equivalent. Ignore the warning about the missing “/srv/www/htdocs-ssl/twiki/lib/LocalSite.cfg” configuration file. You will create it by running the configure script this first time.
    • Input your new administrative password and click Configure button.
    • Click on “General path settings” to expand it:
      • Change the “{DefaultUrlHost}” to match your website’s domain URL.
      • Input “https://localhost” into “{PermittedRedirectHostUrls}” so you can access Twiki from a local browser.
      • Verify that the rest are correct (they should be) and click on Next.
      • Click on Save button, click on “Return to configuration” link, and enter your admin password again.
    • You will see three sections with warnings. We’ll address a couple of those warnings below, but not all. It’s okay to run TWiki with some warnings.
    • Click on “Security setup”.
      • Check “{Register}{AllowLoginName}” if you wish to allow the use of a login ID instead of WikiName.
      • I left the “{Register}{NeedVerification}” unchecked because I haven’t set up SMTP yet. This is okay because once we complete securing the TWiki, only logged-in users will be able to register new users.
      • You might want to increase the “{MinPasswordLength}” to 4 from the default 1 character.
      • You will definitely want to uncheck the “{CryptToken}{Enable}” option because it will cause a browser back action to prevent all Edits and Previews from succeeding in that session. While, I applaud the intent, this feature is flawed. When you preview a page, to re-edit it, you have to hit the Back browser button, and then if you attempt to save, CryptToken will prevent you from doing so. And once this happens, any page you attempt to edit and save will fail. (If you plan never to use Preview or use the browser back button, then you can leave this option on.)
    • Click on “Mail and Proxies”.
      • Uncheck the “{EnableEmail}” option since SMTP wouldn’t work anyhow.
      • Click Next and Save.
  9. Browse to the main TWiki page at https://localhost/twiki/bin/view. You will see a nice congratulations message.
  10. Click on the Registration link under “Main Web Utilities” to register a new user.
    • Just fill in the required info. Once you click Submit, your user will be created and logged into Twiki automatically.
    • Click on the TwikiUsers link on the resulting page.
    • If you want to create another user, click on the TWikiRegistration link and repeat as necessary.
    • Once you are done and back on the TWikiUsers page, log out by clicking on the “Account” menu to the top-right and selecting “Log out”.
  11. For the following, you will need to log in as the administrator.
    • Go to the “Account” menu and select “Log in”. Input “admin” as the username and your administrative password.
    • Click on TWikiUsers and then TWikiGroups after “Related topics”.
    • Creating a new non-admin user group by inputting “TWikiUserGroup” into the “New Group” field and clicking on Add button. Add the WikiNames for non-administrative users to the “Set GROUP =” property. Click on the Save button.
    • Go back to TWikiGroups and click on TWikiAdminGroup to add your user as an administrator. Edit, add your WikiName to “Set GROUP =”, and Save.
    • At the bottom of the resulting page, click on TWikiAdminGroup to add your new user to the administrator group.
    • Now that we have groups and users configured, let’s restrict access to the TWiki.
      • Click on the TWikiAccessControl at the bottom.
      • Scroll down to the “Permissions settings of the webs on this TWiki site” section.
      • Click on the wrench icon before “Main” to edit the Main page permissions.
      • Edit the page and set the following to restrict access to the admin group and our user group.
        Set ALLOWWEBVIEW = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
        Set ALLOWWEBCHANGE = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup,
                             TWikiRegistrationAgent
        Set ALLOWWEBRENAME = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup

        Note: TWikiRegistrationAgent belongs on the same line as %USERSWEB%.TWikiUserGroup.

        It is necessary to allow the TWikiRegistrationAgent to change Main.TWikiUsers to enable new user registration.

      • Save the page.
      • Go back to TWikiAccessControl (link at bottom) and repeat the above access restrictions (without TWikiRegistrationAgent) by clicking on the wrench icon before the “TWiki” link right under “Main” and changing the following:
        Set ALLOWWEBVIEW =  %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
        Set ALLOWWEBCHANGE =  %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
        Set ALLOWWEBRENAME =  %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
      • I disable the “SandBox” instead of setting permissions on it. You can do otherwise.
        Set SITEMAPLIST = off
    • Log out.
  12. Browse to the main TWiki page. You will see a mandatory login form.
  13. Because email was not set up, none of the users have gotten an email containing their randomly generated passwords. To fix this, do the following:
    • Edit the “/srv/www/htdocs-ssl/twiki/data/.htpasswd” file.
      • For each user line, blank out the password by deleting the random character string (encrypted password) between the first colon and second colon.
      • Save the file. Users that you have modified above will now have blank passwords.
    • Ask the users to log in with blank passwords and set their new passwords by doing the following:
      • Click on their name under the top-right Accounts menu.
      • Click on the ChangePassword link at the bottom to set their passwords.
  14. That’s it. Hope that you were able to get it working.

Ease of Use Items:

  • I don’t like the automatic CamelCase or WikiWord linking that TWiki has enabled by default. If I want a link, I will specify so using the square brackets. If you feel the same way, here is how you can disable this feature:
    1. Log into TWiki as a user with administrative privileges or as the default “admin” user.
    2. Click on the “Web Preferences” link on the right navigation table or at the bottom.
    3. Edit the “Web Preferences” page and add the following under “Web settings” section:
      * Set NOAUTOLINK = on
      * Set HIDE_NON_WIKI_WORD_WARNINGS = on
  • The default way to go back to the parent page in TWiki is to hit the browser back button (which breaks CryptToken) or by clicking on the “Backlinks” link at the bottom (too many clicks). I love breadcrumbs and we can add a plugin to TWiki to support this function:
    1. Run the TWiki configure script (https://localhost/twiki/bin/configure). Enter your admin password.
    2. Click on “Extensions” and “Find More Extensions”. Enter your admin password.
    3. Find BreadCrumbsPlugin and click on its “Install” link to the far right. Enter your admin password.
    4. On my system, I got a weird Perl error. If you got the same, we have to install manually by doing the following:
      1. SSH into the linux server.
      2. Change directory to the TWiki installation root directory: “cd /srv/www/htdocs-ssl/twiki”
      3. There should be a script named “BreadCrumbsPlugin_installer” there. Execute it by running “Perl BreadCrumbsPlugin_installer”.
      4. Answer Yes to the re-install module prompt. The installation should complete successfully.
    5. Re-run the TWiki configure script (https://localhost/twiki/bin/configure). Enter your admin password.
    6. Go to “Plugins” and check the “{Plugins}{BreadcrumbsPlugin}{Enabled}” box. Save the change.
    7. Log into the TWiki and edit the “Web Preferences” page to add the following under “Web settings” section:
      * Set BREADCRUMBSPLUGIN_RECORDTRAIL = on
    8. In your wiki pages, add the following “%BREADCRUMBS%” variable at the top and when you view the page, it will be rendered as breadcrumb links.

Some info above derived from:

No Comments

Add Tomcat to the OpenSUSE LAMP Development Server

Linux No Comments

tomcatSome developers needed Java JSP and Servlet support added to our LAMP development server on OpenSUSE 11.3. To do so, we decided to use Tomcat. Follow the instructions below to install Tomcat and the Apache JK Module to integrate Apache with Tomcat.

Install Tomcat 6

  1. As root user, run YaST –> Software –> Software Management. Click on the Search tab.
    • Let’s double-check that the Java SDK is installed already by inputting “jdk” into the search box and clicking on the Search button. You should see that “java-1_6_0-openjdk” and “java-1_6_0-openjdk-plugin” are already checked.
    • Input “tomcat” into the search box and click on the Search button.
    • Check “tomcat” and a bunch of the other entries will get automatically checked as dependencies.
    • Check “tomcat6-webapps” to install the tomcat webapp examples which we will use for testing below.
    • Click on the Accept button at the bottom-right to commit the changes made. YaST will exit once the installation completes.
  2. Strangely, the Tomcat installation might not set some needed permissions on a few tomcat-related directories. Run the following commands to set the missing permissions:
    chmod g+w /var/log/tomcat6
    chgrp tomcat /etc/tomcat6/Catalina/localhost
    chmod g+w /etc/tomcat6/Catalina/localhost
    chmod -R g+w /var/cache/tomcat6

    Double-check that the resulting directories above have “tomcat” as group and that the group write permission is set:

    ls -l /var/log | grep tomcat6
    ls -l /etc/tomcat6/Catalina | grep localhost
    ls -l /var/cache | grep tomcat6

    If you have this issue and don’t run the above commands, you will see “Permission Denied” errors in the “/var/log/tomcat6/catalina.out” log file later.

  3. Some useful info and commands for Tomcat:
    • Service Commands: rctomcat6 start/stop/restart
    • Configuration Location: /etc/tomcat6
    • Logs Location: /var/log/tomcat6
    • Webapps Location: /srv/tomcat6/webapps/
    • Workspace Cache Location: /var/cache/tomcat6
  4. Configure Tomcat to start on bootup by running this command:
    insserv tomcat6
  5. To test the installation, run Tomcat with “rctomcat6 start” and browse to http://localhost:8080/.

Install Apache JK Module

  1. Download a pre-built Apache JK Module for OpenSUSE 11.3. Click on the “Select Mirror” link in the middle and then click on the “binary package” link at the bottom of the page.
  2. Install the downloaded “apache2-mod_jk-1.2.26-6.2.x86_64.rpm” file:
    rpm -ivh apache2-mod_jk-1.2.26-6.2.x86_64.rpm

    This will install to the “/usr/share/doc/packages/apache2-mod_jk” directory and place “mod_jk.so” into Apache’s installation directory at “/usr/lib64/apache2”.

  3. Create an “/etc/tomcat6/worker.properties” file for Apache to define a worker process to connect to Tomcat’s ajp13 handler port (which is enabled by default in “/etc/tomcat6/server.xml” and uses port 8009). I don’t recommend copying from the “/usr/share/doc/packages/apache2-mod_jk/worker.properties” example because it is very out-of-date. Instead, create a “/etc/tomcat6/worker.properties” file with the content below:
    # An ajp13 worker that connects to localhost:8009
    worker.list=ajp13

    # ajp13 worker definition
    worker.ajp13.port=8009
    worker.ajp13.host=localhost
    worker.ajp13.type=ajp13
  4. Create an “/etc/apache2/conf.d/jk.conf” file to configure the Apache JK Module. I suggest copying the “/usr/share/doc/packages/apache2-mod_jk/jk.conf” example to “/etc/apache2/conf.d/jk.conf” and editing the content to match the below:
    # simple configuration for apache (for AJP connector, modul mod_jk.so)
    <IfModule mod_jk.c>
       JkShmFile /var/log/apache2/jk-runtime-status
       JkWorkersFile /etc/tomcat6/workers.properties
       JkLogFile /var/log/apache2/mod_jk.log

       # Log level to be used by mod_jk
       JkLogLevel error

       # The following line makes apache aware of the location of the /examples context
       Alias /examples "/srv/tomcat6/webapps/examples"
       <Directory "/srv/tomcat6/webapps/examples">
           Options Indexes FollowSymLinks
           allow from all
       </Directory>

       # The mounts all JSP files and /servlet/ uri under /examples to be handled by ajp13 tomcat
       JkMount /examples/* ajp13

       # The following line prohibits users from directly accessing WEB-INF
       <Location "/examples/WEB-INF/">
           deny from all
       </Location>
    </IfModule>
  5. Configure Apache to load the JK module:
    a2enmod jk
    a2enmod -l

    The “a2enmod jk” command will add the “jk” module to the list of Apache’s APACHE_MODULES configuration parameter. (This configuration parameter can also be set using YaST –> System –> /etc/sysconfig Editor –> Network –> WWW –> Apache2 –> APACHE_MODULES.)

  6. Restart Tomcat and Apache:
    rctomcat6 restart
    rcapache2 restart
  7. To test the installation, browse to http://localhost/examples/. Try executing the servlets and JSP examples. (Strangely, I was unable to execute two JSP examples, “Basic Arithmetic” and “Functions”, without errors.)
  8. If you encounter errors, check out the “/var/log/tomcat6/catalina.out”, “var/log/apache2/error_log”, and “/var/log/apache2/mod_jk.log” log files. You can increase the amount of info written to “/var/log/apache2/mod_jk.log” by editing “/etc/apache2/conf.d/jk.conf” to set “JkLogLevel info” and restarting Apache.

Some info above derived from Apache2.2 / Tomcat6 / mod_jk / Suse 11.1.

No Comments