Copyright © 2010 Traction Software, Inc.
Installation and Configuration Guide Author: Christopher Nuzum Creation Date and Time: June 2, 2010 1:57 PM
Page 1 of 281
Copyright © 2010 Traction Software, Inc.
Table of Contents Installation and Configuration Guide Doc351: Installation and Configuration Guide
4
Doc191: Overview
5
Doc140: Installing Traction on Windows
7
Doc144: Installing on the Macintosh
23
Doc143: Installing on Linux and Solaris
44
Doc141: Installing Traction TeamPage Upgrades
68
Doc142: Installing a License
69
Doc152: Journal Setup Overview
82
Doc50: Creating a New Journal
83
Doc311: Use an Existing Journal
92
Doc35: Choosing and Configuring a User Directory
97
Doc40: Configuring Active Directory
98
Doc41: Configuring LDAP
120
Doc42: Configuring Multiple LDAP or Active Directory Servers
140
Doc28: Changing User Directories and Migrating Principals
141
Doc305: Troubleshooting Using the Log File Viewer
151
Doc120: First Login with Built-In User Directory
159
Doc116: First LDAP Login
161
Doc115: First Active Directory Login
165
Doc133: How do ACLs Work
166
Doc261: Setting Login Permissions
167
Doc319: Using the Server ACL Editor Intro
168
Doc128: Getting to the Server ACL Editor
176 Page 2 of 281
Copyright © 2010 Traction Software, Inc.
Doc34: Choosing Users
179
Doc33: Choosing Groups
186
Doc262: Setting Permissions
189
Doc13: Applying the ACL
191
Doc31: Checking Effective Permissions
192
Doc192: Overview of the Project ACL Editor
197
Doc127: Getting to the Project ACL Editor
205
Doc45: Configuring SMTP
209
Doc44: Configuring Projects to Read Mail
222
Doc131: How HTTPS Works
227
Doc264: Setting up HTTPS
228
Doc132: How HTTPS with X.509 Client Certificates Works
250
Doc93: Enabling HTTPS with Required X.509 Client Certificates
251
Doc94: Enabling LDAP Authentication with X.509 Client Certificates
268
Doc193: Using the Trust Manager
270
Page 3 of 281
Copyright © 2010 Traction Software, Inc.
Installation and Configuration Guide Installation and Configuration Guide Doc351: April 29, 2008 11:03 AM, Posted by Christopher Nuzum, Edited by Jordan Frank
•
• • •
•
•
•
•
Installing Traction • Overview • Installing Traction on Windows • Installing on the Macintosh • Installing on Linux and Solaris Installing Traction TeamPage Upgrades Installing a License Configuring a Journal • Journal Setup Overview • Creating a New Journal • Use an Existing Journal Choosing and Configuring a User Directory • Configuring Active Directory • Configuring LDAP • Configuring Multiple LDAP or Active Directory Servers • Changing User Directories and Migrating Principals • Troubleshooting Using the Log File Viewer Getting Started with ACLs • First Login • First Login with Built-In User Directory • First LDAP Login • First Active Directory Login • How do ACLs Work • Setting Login Permissions • Using the Server ACL Editor • Using the Server ACL Editor Intro • Getting to the Server ACL Editor • Choosing Users • Choosing Groups • Setting Permissions • Applying the ACL • Checking Effective Permissions • Using the Project ACL Editor • Overview of the Project ACL Editor • Getting to the Project ACL Editor Configuring Email • Outgoing • Configuring SMTP • Incoming • Configuring Projects to Read Mail Configuring HTTPS and X.509 Certificates • How HTTPS Works • Setting up HTTPS • How HTTPS with X.509 Client Certificates Works • Enabling HTTPS with Required X.509 Client Certificates Page 4 of 281
Copyright © 2010 Traction Software, Inc.
• •
• Enabling LDAP Authentication with X.509 Client Certificates Using the Trust Manager • Using the Trust Manager For Deployments which have licensed the Premium Search Module • Installing the Attivio Search Option for Traction TeamPage • For deployments which must continue to use the FAST Search Module which is now replaced by the Attivio Search Module, see Installing and Configuring the FAST Search Option
Overview Doc191: March 22, 2008 4:11 PM, Posted by Documentation Importer, Edited by Greg Lloyd
Traction TeamPage is a Java language application that provides Web server, database, search engine and hypertext Journal functions to implement TeamPage blog, wiki, tagging and Enterprise 2.0 collaboration capabilities described in the Traction User Guide. In order to deploy and use your own instance of a Traction TeamPage server you will need: 1) A physical or virtual computer running one of the supported host operating systems in order to run the Traction TeamPage software as a server for your own company or use; 2) A license file for Traction TeamPage. To review the hardware and software requirements and recommendations for running Traction TeamPage, please see TeamPage System Requirements. See Welcome to Traction TeamPage - Download and Getting Started for the current software download link, computer hardware and operating system requirements, and access to a free TeamPage5 license. If you purchased a larger TeamPage license, you should have received a license file for your TeamPage configuration by email. See http://www.TractionSoftware.com's Buy page for license information. If you need help purchasing a license please email
[email protected]. The Traction TeamPage installation procedure for each host operating system is described in the following chapters. Follow the step-by-step instructions for the Operating System You may wish to review the following Frequently Asked Questions before installing.
Pre-Installation FAQ What port does Traction run on? By default, the Traction server runs on port 8080, although you can select a different port during installation or at any time later using the web-based server setup interfaces.
How can I change the port Traction uses? Traction provides a web-based interface that allows you change Traction's port, or you can change the port= line in the Traction/traction/server/Traction.properties file while the server is not running to select a different port.
Can Traction run on the same port as another web server, e.g. Apache or IIS Yes, provided that you configure the machine to have multiple IP addresses and you configure both the other server and Traction to bind to only one of the available IP addresses. If you are not familiar with how to do this, contact Traction Software support for a FAQ.
What if I already have a server running on the port Traction uses? Page 5 of 281
Copyright © 2010 Traction Software, Inc.
If you already have a process using that port, Traction will not be able to start and will report the error:
If you are running as a Windows service or Unix daemon, Traction will exit without requiring a keypress. If your service or daemon never starts up, this may be the problem. You can check the logfile to see if this happened. To resolve this, you can choose a different port, or enable binding to a different IP address.
Where is Traction's logfile? The status logfile is in the folder Traction/traction/server/logs/traction.log inside the installation directory, e.g. /usr or C:\Program Files.
If I install on one computer, can I move Traction to another computer later? Yes, this is very straightforward. If the journal is stored in the default location in the server directory, you can just copy the server directory to the corresponding location on the new machine and re-run the installer. Re-running the installer is the standard upgrade procedure and will install any platform-specific run scripts or registry settings. Finally, you'll need to set up any auto-start and auto-shutdown capabilities that you may have configured. If the journal is stored outside the server directory, you may need to move this file so it is available to the other machine, then use the Journal Setup interface to tell Traction the location of the journal.
Can I move Traction to a different operating system, e.g. from Widows to Linux? Yes. Traction's data files are fully portable between platforms in all locales, so you can even move journals with Japanese share folders between platforms. The procedure is the same as for moving between machines (described above), except that you will need to run the Traction installer for the new platform after copying the server directory.
Can I run Traction on protected ports like port 80 or 443? Yes, provided that Traction run as a Windows Administrator account or a Unix root user. Ports less than 1024 can only be accessed by programs running with root/Administrator permissions.
If I want to run on port 80, do I really have to run as root/Administrator? Techniques for working around this requirement exist, but tend to be very platform and installation specific and are outside the scope of what we cover in this guide. Depending on your platform, you may be able to reroute traffic from port 80/443 to other ports. For example, on Solaris and BSD, you might add a line like this to ipnat.conf: rdr dnet0 192.168.2.1/32 port 80 -> 192.168.2.1 port 8080 Page 6 of 281
Copyright © 2010 Traction Software, Inc.
If you replace dnet0 with the interface you want to remap from and 192.168.2.1 with the IP address of the host running Traction, traffic on port 80 can be shifted to a non-root process on, in this case, Traction's default port 8080. On Linux you can do the same thing using ipchains. Some customers use a port-forwarding router to direct traffic to other ports.
Do I Need X11 to Install Traction on Linux or Solaris Systems? Even for a console install? No, X11 should not be required for a headless install.
How do I back up the software? To back up Traction, you need to copy the Installation and Journal directories. See Backup and Maintenance for more details.
Installing Traction on Windows Doc140: March 22, 2008 4:05 PM, Posted by Documentation Importer, Edited by Jordan Frank
First download the 32 or 64 bit Windows installer from the Traction TeamPage Server Installers Page.
If provided, you can instead click the button on the installers page that says "Click here to Install". Note: The Traction installer requires at least a 256-color display to run. The splash screen appears and lets you choose the language you would like to use for installing.
Page 7 of 281
Copyright © 2010 Traction Software, Inc.
After choosing your language and clicking OK, you come to the first installer panel.
Page 8 of 281
Copyright © 2010 Traction Software, Inc.
Press next to go to the license agreement panel.
Page 9 of 281
Copyright © 2010 Traction Software, Inc.
Read the license agreement, then click the "I accept the terms of this License Agreement" radio button. You will not be able to continue the installation if you do not accept the terms. If you do not wish to accept the terms, you may cancel the installation.
After accepting the license, the installer displays upgrade information.
Page 10 of 281
Copyright © 2010 Traction Software, Inc.
For additional upgrade information, see the Help section Installing Traction TeamPage Upgrades. At this point, you will want to make sure that Traction is not running. The installer will remind you about this.
Page 11 of 281
Copyright © 2010 Traction Software, Inc.
Clicking the "Next" button will take you to the service selector.
Page 12 of 281
Copyright © 2010 Traction Software, Inc.
This selector allows you to choose whether you would like to install as a Windows service. A Windows Service is a program that runs invisibly in the background, and which is normally started automatically when the computer powers on. Some previous versions of Traction provided two types of services that had different capabilities. Improvements to the Windows service mode in version 3.7 mean that you don't have to choose between two different services, but only whether you want to install the service. If you want your Traction server to run automatically, you will want to install the service. Next you will be asked to select the location where the Traction application should be installed.
Page 13 of 281
Copyright © 2010 Traction Software, Inc.
The Java Runtime Environment and all application and configuration files will be installed in this directory. By default, all subsequent data files are also created in this directory, although during Journal creation you can select to locate your data in a different location. Next, you will be asked to choose a name for your Traction service. If you plan on installing more than one Traction server on the same machine, each instance must have a different service name. The service will appear on the Windows Services control panel as the name you select.
Page 14 of 281
Copyright © 2010 Traction Software, Inc.
Next you can choose where to create icons.
Page 15 of 281
Copyright © 2010 Traction Software, Inc.
Before file copying commences you can review your settings.
Page 16 of 281
Copyright © 2010 Traction Software, Inc.
If you are satisfied with your selections, click "Install". Otherwise you can go to earlier panels or cancel. After file copying completes, you can optionally configure the initial network settings. If you are running multiple instances of Traction on the same computer, either the port must be different for each instance, or you must specify a different bind address for each instance and check the "Bind to a specific IP address" checkbox.
Page 17 of 281
Copyright © 2010 Traction Software, Inc.
Next, if you installed a service, you are given the opportunity to start the service.
Page 18 of 281
Copyright © 2010 Traction Software, Inc.
We normally recommend that you select "I will start the service later myself". This lets you set up your system and verify that everything is running correctly before starting the service, since there is no easy way to see status or error output from the Service. Note: if you start as a service, you will not be shown the URL by which to contact Traction. If everything succeeds you will see the confirmation panel.
Page 19 of 281
Copyright © 2010 Traction Software, Inc.
Press next to continue.
Page 20 of 281
Copyright © 2010 Traction Software, Inc.
Normally the online help will be displayed at the end of the installation. If you do not wish to see the help, uncheck the "Show Help Now" checkbox before pressing "Done" to exit the installer. If you started the service, you can go your Traction server's URL now. Otherwise, you can now start the Traction Application. If you chose the defaults, you now have a Traction program group in your start menu, with two programs: TractionApplication and Rebuild.
Page 21 of 281
Copyright © 2010 Traction Software, Inc.
To start Traction, run TractionApplication. The server should start up in a DOS window. The URL for your Traction server is displayed on the last line.
Open a web browser and enter that URL.
Page 22 of 281
Copyright © 2010 Traction Software, Inc.
You can now proceed to the next step, Installing a License.
Installing on the Macintosh Doc144: March 22, 2008 4:06 PM, Posted by Documentation Importer, Edited by Jordan Frank
Page 23 of 281
Copyright © 2010 Traction Software, Inc.
On the Traction TeamPage Server Installers Page, either click the "Download Installer for Mac OS X" button or download and run the installer.
If you see a security warning, proceed with the download.
Page 24 of 281
Copyright © 2010 Traction Software, Inc.
If your browser did not automatically unzip the zip file, find the zip file and unzip it, then run the installer app by double-clicking the icon.
The installer will start to run. The splash screen appears and lets you choose the language you would like to use for installing.
Page 25 of 281
Copyright © 2010 Traction Software, Inc.
After choosing your language and clicking OK, you come to the first installer panel.
Page 26 of 281
Copyright © 2010 Traction Software, Inc.
Press next to go to the license agreement panel.
Page 27 of 281
Copyright © 2010 Traction Software, Inc.
Read the license agreement, then click the "I accept the terms of this License Agreement" radio button. You will not be able to continue the installation if you do not accept the terms. If you do not wish to accept the terms, you may cancel the installation.
After accepting the license, the installer displays upgrade information.
Page 28 of 281
Copyright © 2010 Traction Software, Inc.
For additional upgrade information, see the Help section Installing Traction TeamPage Upgrades. Next, Traction displays an important warning that if you are upgrading Traction, you should shut down the instance that you are upgrading.
Page 29 of 281
Copyright © 2010 Traction Software, Inc.
Next, you can select the location where the Traction application should be installed. Important! Unless you are familiar with Unix and the Terminal, we recommend that you accept the default location. Generally the only time Macintosh users need to change this is when they are installing multiple Traction servers on the same computer.
Page 30 of 281
Copyright © 2010 Traction Software, Inc.
All application and configuration files will be installed in this directory. By default, all subsequent data files are also created in this directory, although during Journal creation you can select to locate your data in a different location. Before file copying commences you can review your settings.
Page 31 of 281
Copyright © 2010 Traction Software, Inc.
If you are satisfied with your selections, click "Install". Otherwise you can go to earlier panels or cancel. After file copying completes, you can optionally configure the initial network settings. If you are running multiple instances of Traction on the same computer, either the port must be different for each instance, or you must specify a different bind address for each instance and check the "Bind to a specific IP address" checkbox.
Page 32 of 281
Copyright © 2010 Traction Software, Inc.
Press next to show a summary of the installation.
Page 33 of 281
Copyright © 2010 Traction Software, Inc.
You can now press done to exit the installer.
Running Traction There are three ways to run Traction on your Macintosh: • • •
As an Application . This is simplest for getting started. Using Terminal. This is useful for troubleshooting, and we recommend that you run this way to complete your initial installation of Traction. Automatically on operating system Start and Shutdown. This is recommended for production use.
Running Traction as an Application If you just wish to run Traction periodically, you can use the TractionOSX.app program to run it. A shortcut to this icon is normally placed on the desktop during installation.
The doc icon will bounce while Traction is starting up; when it stops bouncing, you should be able to reach Traction via the configured URL (the default is http://localhost:8080). If you have trouble contacting Page 34 of 281
Copyright © 2010 Traction Software, Inc.
the Traction server after clicking the icon, please see "Running Traction from the Terminal" for troubleshooting and diagnostic information. Note that when you run this way, clicking the dock icon has no effect; it only serves as an indication that Traction is running. When you are ready to stop Traction, you should use the "shutdown Traction" button in Server Setup | General.s
Running Traction from the Terminal To complete your initial Traction installation and configuration, we recommend that you run Traction from the Terminal program. To do this, run the Terminal program, which lives in the /Applications/Utilities folder.
Type cd /Applications/Traction/traction/server/ Press Enter, then type ./run
Page 35 of 281
Copyright © 2010 Traction Software, Inc.
When you press Enter, the program will start. Your terminal should look something like this:
The URL for your Traction server is displayed on the last line, in this case http://plum.local:8080. Open a web browser and enter that URL. You should be redirected to a page that looks like this:
Page 36 of 281
Copyright © 2010 Traction Software, Inc.
You can now proceed to the next step, Installing a License. If you need to, you can shut down your Traction server cleanly by typing control-c in the Terminal window.
Page 37 of 281
Copyright © 2010 Traction Software, Inc.
After shutting it down, you can run it again using the ./run command, or you can use the SystemStarter scripts described above to have Traction always running silently in the background for you.
Configuring Traction to Start and Shutdown Automatically Traction includes an installer that installs the necessary scripts to /Library/StartupItems to make Traction start automatically on boot and shutdown cleanly on shutdown. Important! These scripts assume that Traction is installed in /Applications/Traction. If you installed your Traction server in a different folder, you will need to edit the variable TRACTIONDIR in /Library/StartupItems/Traction/Traction after completing the installation. To run this installer, open the folder /Applications/Traction/traction/server/extras/scripts and double-click the TractionRunner.pkg.zip to unzip the installer.
The installer icon should appear.
Double-click this icon to run the installer.
Page 38 of 281
Copyright © 2010 Traction Software, Inc.
Click continue to choose a destination.
Page 39 of 281
Copyright © 2010 Traction Software, Inc.
Select your boot volume, then press continue.
Page 40 of 281
Copyright © 2010 Traction Software, Inc.
When you click the Install button, you will be required to enter your password:
Page 41 of 281
Copyright © 2010 Traction Software, Inc.
When you press OK, the installation is performed. When the installation completes, you should see the confirmation screen.
Page 42 of 281
Copyright © 2010 Traction Software, Inc.
Press the close button to close this screen. Important! If you installed your Traction server in a different folder, you will now need to edit the variable TRACTIONDIR in /Library/StartupItems/Traction/Traction.
Using the Start/Stop Script from the Terminal After you have completed installing and configuring your Traction server, you can start and stop it from the Terminal using these commands. To start Traction from the terminal, run: sudo /sbin/SystemStarter start Traction to stop Traction cleanly from the terminal, type sudo /sbin/SystemStarter stop Traction You will be required to enter your password.
Disabling the Start/Stop Script To disable Traction from starting automatically, or after uninstalling Traction, you need to remove the scripts that this installer installs. To do this, type the following in the console: Page 43 of 281
Copyright © 2010 Traction Software, Inc.
sudo rm -r /Library/StartupItems/Traction You will be required to enter your password.
Installing on Linux and Solaris Doc143: March 22, 2008 4:05 PM, Posted by Documentation Importer, Edited by Jordan Frank
First download the Traction TeamPage Server Installer for your platform. Important! Note: Due to a problem with the ZeroG InstallAnywhere installer, X11 libraries must be installed on the target system, even for console-only installations. We apologize for this inconvenience. As soon as ZeroG has a fix for this problem we will release installers that do not suffer this limitation. You can do either a Console installation or an X11 Installation. At the end of this chapter there are instructions on configuring the Traction server to start and stop as a daemon.
Console Installation To start the installer in console mode, sh the downloaded installer with the -i console flag passed.
Next, chose a locale for the installer.
Page 44 of 281
Copyright © 2010 Traction Software, Inc.
Press enter after reading each of the information pages.
To accept the terms of the license agreement, press Y and Enter to continue.
Page 45 of 281
Copyright © 2010 Traction Software, Inc.
The installer will then remind you to make sure that if you are upgrading, you shut down the running Traction instance before proceeding.
Please don't skip this important step! Once you have verified that Traction is no longer running, press Enter to continue. Choose the path where you would like to install Traction. Some popular choices are /opt, /opt/traction, /usr, /usr/local, /usr/local/traction.
Page 46 of 281
Copyright © 2010 Traction Software, Inc.
Next, you can choose the Java Virtual Machine (JVM) to be used to run Traction. The installer tries to list all the installed JVMs.
In almost all cases, we recommend that you choose option 1, the default: Install a Java VM specifically for this application. In certain circumstances, such as when you wish to run Traction using 64-bit mode on Solaris on a SPARC architecture, you will need to specify another JVM already installed on the system. A summary will appear to let you review your changes before running the installer.
Page 47 of 281
Copyright © 2010 Traction Software, Inc.
During the installation a progress meter will show the percentage of the installation completed.
After the files have been copied, you can specify the initial network settings for Traction. If you're not sure, you can accept the defaults; these settings can be changed later via the Traction interface or by editing the Traction.properties file while the server is not running.
If you install on a port less than 1024, you will need to run as root. If you wish to serve on port 80, but not run with root privileges, you can Overview, or use Apache ProxyPass as a front-end. If you wish to use ProxyPass, contact Traction Software support for instructions.
Page 48 of 281
Copyright © 2010 Traction Software, Inc.
If you wish to enter a bind address, choose option 2; the installer will prompt you for the address to use. After the network settings have been written, the following message will appear:
To start Traction in the foreground (during initial configuration), change to the traction/server subdirectory of the installation directory and run TractionApplication:
Page 49 of 281
Copyright © 2010 Traction Software, Inc.
To continue the configuration, open a web browser and navigate to the URL shown.
Page 50 of 281
Copyright © 2010 Traction Software, Inc.
You can now proceed to the next step, Installing a License.
X11 Installation To start the installer in X11 mode, you will need to have a valid DISPLAY configured. Then, sh the downloaded installer. You should see the following on your console.
Page 51 of 281
Copyright © 2010 Traction Software, Inc.
Then a small window should appear prompting you for the locale in which you would like to perform the installation.
After you choose a locale and press OK, you will see a welcome screen.
Page 52 of 281
Copyright © 2010 Traction Software, Inc.
Press next to go to the license screen. To enable the Next button, you must accept the terms of the license agreement.
Page 53 of 281
Copyright © 2010 Traction Software, Inc.
The next screen explains the upgrade procedure.
Page 54 of 281
Copyright © 2010 Traction Software, Inc.
The installer will then remind you to make sure that if you are upgrading, you shut down the running Traction instance before proceeding.
Page 55 of 281
Copyright © 2010 Traction Software, Inc.
Please don't skip this important step! Once you have verified that Traction is no longer running, press Enter to continue. Next, choose the path where you would like to install Traction. Some popular choices are /opt, /opt/traction, /usr, /usr/local, /usr/local/traction.
Page 56 of 281
Copyright © 2010 Traction Software, Inc.
A summary will appear to let you review your changes before running the installer.
Page 57 of 281
Copyright © 2010 Traction Software, Inc.
During the installation a progress meter will show the percentage of the installation completed.
Page 58 of 281
Copyright © 2010 Traction Software, Inc.
After file copying completes, you can optionally configure the initial network settings. If you are running multiple instances of Traction on the same computer, either the port must be different for each instance, or you must specify a different bind address for each instance and check the "Bind to a specific IP address" checkbox.
Page 59 of 281
Copyright © 2010 Traction Software, Inc.
When the network settings have been written, the following message will appear:
Page 60 of 281
Copyright © 2010 Traction Software, Inc.
cd To start Traction in the foreground (during initial configuration), change to the traction/server subdirectory of the installation directory and run TractionApplication:
Page 61 of 281
Copyright © 2010 Traction Software, Inc.
To continue the configuration, open a web browser and navigate to the URL shown.
Page 62 of 281
Copyright © 2010 Traction Software, Inc.
You can now proceed to the next step, Installing a License.
Configuring Traction to Start and Shutdown Automatically Bundled with Traction is a script that can be used to start and stop Traction when the system changes runlevel (on boot and shutdown). The script is shipped as server/extras/scripts/S99Traction. Important! If you plan to run multiple Traction instances on the same machine, you will need to make multiple copies of the script, one for each instance, and you will need to follow the instructions for stopping via URL instead of via signal.
On both Solaris and Linux Page 63 of 281
Copyright © 2010 Traction Software, Inc.
1. Copy the script S99Traction to /etc/init.d/traction (thus renaming it to traction in the process). cp extras/scripts/S99Traction /etc/init.d/traction
On Solaris 2. Create two symlinks to /etc/init.d/traction: /etc/rc2.d/S99Traction and /etc/rc2.d/K99Traction cd /etc/rc2.d ln -s /etc/init.d/traction S99Traction ln -s /etc/init.d/traction K99Traction
Installing on Linux 2. cd /etc/init.d 3. chkconfig --add traction
Configuring the Script The script is listed below, with explanations under each section that you may wish to customize. #!/bin/sh # # chkconfig: 35 99 10 # description: Traction startup script to start up hosting servers # Which Traction wrapper script to run. ############################################################################# TRACTION_PROGRAM=./TractionDaemon Normally on Unix systems you should run TractionDaemon. This wrapper tells the underlying Traction process to ignore lockfiles, but listens for signals like -2 (shutdown) and -3 (generate thread trace). # Path of the local installation's server traction/server directory. ############################################################################# TRACTIONDIR=/opt/r36beta2/traction/server The script needs to know where your Traction system is installed. Enter the complete path to the server directory of your Traction installation. # User as whom to run Traction. Must be root to run on ports less than 1024. # If running as a different user, make sure to chown both the entire # Traction program and journal directories to that user. ############################################################################# TRACTIONUSER=root Page 64 of 281
Copyright © 2010 Traction Software, Inc.
By default, this script runs Traction as root, but you can run Traction as a less privileged user by entering the name of that user here. The user you enter must exist and have full permissions to the entire Traction installation and the journal directory. Note: This script does not support running on ports less than 1024 as another user. If you desire this configuration, you will need to configure ipchains (on Linux) or ipnat (on Solaris) to remap those ports to a higher-numbered port used by Traction. # Path of file to which errors should be logged. ############################################################################# LOGFILE=traction.out This file is used to capture output from this script. The path is relative to the server directory. # Load system standard function definitions ############################################################################# case "`uname -a`" in Linux*) . /etc/rc.d/init.d/functions psflags=-auxwwww ;; SunOS*) psflags=-ef ;; Darwin*) echo "Use server/extras/scripts/TractionRunner.pkg.zip to start and stop on OS X" exit 0; esac RETVAL=0 start() { echo "Starting Traction servers" if [ -d $TRACTIONDIR ] then ( cd $TRACTIONDIR ; su $TRACTIONUSER -c "$TRACTION_PROGRAM $TRACTION_FLAGS" >> $LOGFILE 2>&1 ) & fi } Page 65 of 281
Copyright © 2010 Traction Software, Inc.
The section below is used to configure stopping Traction via an HTTP request to the Traction server as a Traction administrator. The request generated is the same as clicking the "shutdown Traction" button in Server Setup | General. If Traction is the only Java program running on the computer, and you are only running one Traction server, you should not need this. Note: If you are running HTTPS with X.509 client certs, or are using realms or another non-cookie authenticator, this option will not work; you must use the signal-based method below to perform a clean external shutdown of Traction servers configured with these options. ############################################################################# # StopTraction setup - Optional # if you have multiple Traction servers running on the same box, you # can use the StopTraction script to target which one you want to # stop. This script requires the following information. # IP address of the server to stop IPADDRESS=localhost Enter the IP address of this Traction server. Normally localhost should suffice. # PORT to contact to shutdown PORT=8080 Enter the port your Traction server runs on. # if your server does not run HTTPS, comment out the second line below. HTTPS= #HTTPS=-https If you are using https, un-comment the second line. This will cause the -https option to be passed to Traction. # username of an admin account on your Traction sever. USERNAME=admin Enter the Traction username of an account with server setup access on your Traction server. # password of an admin account on your Traction sever. To protect this # information, we suggest that if you use this option, you chmod this # script 700. PASSWORD=sample Enter the password for the above account. As indicated in the comment, we recommend that you chmod 700 this script so that only root can read the password. ############################################################################# Page 66 of 281
Copyright © 2010 Traction Software, Inc.
stopurl() { echo "Stopping Traction servers" if [ -d $TRACTIONDIR ] then ( cd $TRACTIONDIR; ./StopTraction $HTTPS -u $USERNAME -p $PASSWORD ${IPADDRESS}:${PORT} ) fi } stop() { echo "Stopping Traction servers" # this works by looking up the last Traction JRE thread to start, which should # belong to the server, not the StartTraction script. traction_thread_pid=`ps ${psflags} | grep 'jre/bin/java' | grep -v grep |sort -k 2n |tail -1 | awk '{print $2}'` if [ -n "${traction_thread_pid}" ] ; then echo "Traction process found on ${traction_thread_pid}. Sending signal 2 ." kill -2 ${traction_thread_pid} RETVAL=$? else echo "No Traction process identified." fi } traction_status() { tail -f $TRACTIONDIR/$LOGFILE } case "$1" in start) start ;; stop) stop Page 67 of 281
Copyright © 2010 Traction Software, Inc.
If you would like to use the URL method for shutdown, rewrite the line immediately above to read stopurl instead of stop. ;; stopurl) stopurl ;; status) traction_status RETVAL=$? ;; log) (cd $TRACTIONDIR; less $LOGFILE) ;; restart) stop start ;; *) echo $"Usage: $prog {start|stop|status|restart|condrestart}" exit 1 esac exit $RETVAL When the system changes runlevels, the start and stop methods will be called. This should take care of stopping and starting your Traction server.
Installing Traction TeamPage Upgrades Doc141: March 22, 2008 4:05 PM, Posted by Documentation Importer, Edited by Christopher Nuzum
The Traction installer is designed to perform both fresh installs and upgrades using the same installation procedure. The upgrade will not overwrite your existing journals or configuration files that you have added. Generally upgrades can be performed in 15 minutes or less. For systems that require high availability, Traction supports a low downtime upgrade procedure; contact
[email protected] for detailed instructions. Page 68 of 281
Copyright © 2010 Traction Software, Inc.
To upgrade an existing Traction installation, you will repeat the identical steps you used to perform the original install, selecting the same location into which to install. - Installing on the Macintosh - Installing Traction on Windows - Installing on Linux and Solaris In order to prepare for and execute the upgrade process, follow these steps: 1. Download the current version of the correct installer for your server platform. 2. Before shutting down Traction, Check Server Setup | Server Files for Active Threads. You can determine if there is current user activity in this window. 3. Shut down Traction by stopping the service or by clicking Shut Down Traction in Server Setup | General. 4. Backup your Program Files\Traction directory and (if it's not a sub-directory) your Journal directory. Your journal directory's location is visible in Server Setup | General under Journal Information, and is specified in the curdb= property in the Program Files\Traction\traction\server\Traction.properties file. You can generally perform the backup by just copying and pasting the folders into a different location. 5. Run the Installer, specifying the same location as the original installation, e.g. c:\Program Files\Traction as the installation location. On Windows you should always reinstall the service during each upgrade as well. 6. Restart the Traction server in the normal manner (unless you selected the installer option to let the Service run automatically when install is complete.
Installing a License Doc142: March 22, 2008 4:05 PM, Posted by Documentation Importer
Your license should be sent to you as an email attachment named Traction.lic. If you do not have a license, you can follow the instructions below for requesting an evaluation license. First, save the Traction.lic file locally on your computer. Next click the Go button next to "install a license file".
Page 69 of 281
Copyright © 2010 Traction Software, Inc.
This takes you to the license handler page.
Page 70 of 281
Copyright © 2010 Traction Software, Inc.
Click the Browse button and use the file selector to choose your Traction.lic file. Note that Windows may hide the .lic extension, depending on your Explorer settings. When the extension is hidden, it will give you a rollover that identifies the type as a license.
Page 71 of 281
Copyright © 2010 Traction Software, Inc.
After you have chosen the file, press Open. The file path will appear in the file chooser. Once it appears, click Next.
Page 72 of 281
Copyright © 2010 Traction Software, Inc.
After you click Next, you will be taken to a page that shows your license information.
Page 73 of 281
Copyright © 2010 Traction Software, Inc.
Page 74 of 281
Copyright © 2010 Traction Software, Inc.
You can now click "next" to continue to Journal Setup Overview.
Requesting an Evaluation License If you obtained a copy of Traction without a license, you can request an evaluation license. To do this, click the Go button next to "Get an evaluation license". You will need to have an internet connection to obtain an evaluation license this way.
This takes you to the license server welcome page.
Click the "next" button to continue. On certain versions of Windows, you may get a security warning like:
Page 75 of 281
Copyright © 2010 Traction Software, Inc.
If you get this warning, click "Yes" to proceed to the license information form. Fill in this form.
Page 76 of 281
Copyright © 2010 Traction Software, Inc.
Page 77 of 281
Copyright © 2010 Traction Software, Inc.
When you have finished the form, click the "register" button at the bottom of the page. This will take you to a confirmation page where you can review the details. If you notice an error, use your browser's "go back" button to return to the previous page and make any necessary changes.
Page 78 of 281
Copyright © 2010 Traction Software, Inc.
Page 79 of 281
Copyright © 2010 Traction Software, Inc.
When you have reviewed the details, click the next arrow to install the license in your server. The installed license details will be displayed again..
Page 80 of 281
Copyright © 2010 Traction Software, Inc.
Page 81 of 281
Copyright © 2010 Traction Software, Inc.
You can then click next to go to[Journal Setup Overview]
Journal Setup Overview Doc152: March 22, 2008 4:06 PM, Posted by Documentation Importer
A Traction Journal is the container that houses all your data. This includes user accounts, projects, articles, labels, shared files and attachments. • User accounts/profiles store user identify and preference information. Even when users are defined in external directory systems like Active Directory or LDAP, a Traction profile is created for each user to store the user's preferences. • Projects are spaces into which Articles, Comments, and Files can be published. Each Project has an Access Control List (ACL) that governs what each User is allowed to do inside that Project (the user's Permissions). • Articles are pieces of text, HTML, or metadata that can be published into Projects. • Labels are categories that can be applied to Articles. Each Project can have its own Labels. Labels from any Project can be placed on any Article in any Project. Labels provide a convenient way to gather and organize Articles. Labels in Traction are used for describing content, expressing status and priority, indicating where Articles should appear in the interface, and for modeling taxonomies. • Attachments are files that are connected to Articles, much like email attachments. • Shared Files are files or directories (folders of files and folders) that are connected either to Articles or Projects. In Traction, Attachments and Shared Files can be versioned and accessed via WebDAV (Web Folders on Windows). By default, journals start nearly empty and can be configured to match your needs. All the files that comprise a journal are stored on disk in a single folder, or directory, the "journal directory". You can have multiple journals, but only one may be active at a time in any given instance of the Traction program. Traction Software provides a small number of sample journals to get people started, and also offers journal creation training and consulting to help customers create a journal that fulfills their requirements. If you have gone through such consulting and are installing a journal provided to you, follow the steps below for "Use Existing Journal". The Journal Setup page gives you two options: Creating a New Journal or Use an Existing Journal.
Page 82 of 281
Copyright © 2010 Traction Software, Inc.
If you are familiar with Traction and wish to create a new, empty journal, select the radio button next to Creating a New Journal. Otherwise, choose Use an Existing Journal to get acquainted with Traction using the Traction Starter Journal. You can now continue on to Creating a New Journal or Use an Existing Journal.
Creating a New Journal Doc50: March 22, 2008 3:52 PM, Posted by Documentation Importer
Naming the Journal Directory To create a new journal, first type a name for the directory. This directory will be created within the server/ directory. The name you choose must be a valid directory name on your operating system. We recommend that you not use any spaces or punctuation characters.
Page 83 of 281
Copyright © 2010 Traction Software, Inc.
Choosing the Default Language At this point, you can also choose a default language for your Journal. The language that you select will determine the names of default labels and sections. You can change your journal's default language later.
Once you have chosen a name and default language, click the Next button to go to the Journal Setup page:
Page 84 of 281
Copyright © 2010 Traction Software, Inc.
This page lets you quickly create a journal to start working in. From here you can connect to LDAP or Active Directory and create starting user accounts. If you are creating a new journal while running an existing journal, you can carry over the usernames and passwords from your existing journal. The first thing this page reports is the directory in which the new Journal will be created. On a default Windows implementation, it might look like this:
Page 85 of 281
Copyright © 2010 Traction Software, Inc.
Setting a Description Next, you can type a brief description for your Journal.
Choosing a Default Project Template Next you can choose what template you would like to use (by default) for creating new projects.
A description of each template appears underneath the selected template.
Selecting a User Directory Page 86 of 281
Copyright © 2010 Traction Software, Inc.
Next you can choose and configure a User Directory, which is where the list of users is drawn from and maintained. The first time you create a journal, Traction will default to its built-in (Journal) based User Directory:
If you have already set up a journal, the User Directory listed will default to the one used in your current journal. If you would like to configure LDAP, Active Directory, or another external User Directory, or you would like to learn more about the available User Directory options, please follow the instructions in the section Choosing and Configuring a User Directory before continuing. Select the user directory that you would like to use. You can change user directories later, and even migrate between user directories, e.g. from the built-in Journal directory to Active Directory, from Active Directory to LDAP, or from either of those to the Journal.
Choosing an Attachment Store Next, choose whether to enable WebDAV for attachments (to learn more about WebDAV in Traction, see the section How is WebDAV Used in Traction TeamPage). Note: WebDAV access is provided by default Where are Files Shared and Managed in TeamPage regardless of whether it is enabled for attachments. If you would like to turn on WebDAV for attachments, select WebDAV attachment store.
Adding User Accounts Note: If the User Directory you selected is configured to be the exclusive source of users, the people section will not appear, and you can skip to the next step. This section lets you quickly create users. To create a user, choose a username and password, then click the +) button.
Page 87 of 281
Copyright © 2010 Traction Software, Inc.
When you click the +) button, the account will be added to the list on the right and selected.
You can click the (- button to remove the selected user. Repeat this process for as many users as you like. You can change usernames and passwords later, but you should make sure to include one username for yourself with a password that you won't forget; you will need it when you first login to Traction.
Select an Initial Server Administrator Note that one user must be designated as the initial server administrator. This is the user you will need to log in as to first access the Server Setup pages in your configured journal.
Page 88 of 281
Copyright © 2010 Traction Software, Inc.
Creating the Journal When you are ready to create your journal, click the Next button at the bottom of the page.
This will initiate a restart and initial index creation.
When the restart has completed, you will see the following message, and the Next button will become enabled.
Page 89 of 281
Copyright © 2010 Traction Software, Inc.
When you click the Next button, you will be brought to your live journal for the first time. Depending on the user directory you created, you may get a login screen or a Front Page. If you are using NTLM and Active Directory, you should already be logged in using your Windows login account.
Page 90 of 281
Copyright © 2010 Traction Software, Inc.
Page 91 of 281
Copyright © 2010 Traction Software, Inc.
You can now proceed to the section First Login Configuring Permissions via ACL which will explain how to complete the initial setup by defining permissions.
Use an Existing Journal Doc311: March 22, 2008 4:24 PM, Posted by Documentation Importer
Selecting an Existing Journal The list of known Journals is shown next to the Use Existing Journal radio button.
Page 92 of 281
Copyright © 2010 Traction Software, Inc.
Traction currently ships with two journals: StarterJournal, which includes some sample content to help familiarize you with Traction, and CommunicatorJournal_ja, which has similar content in Japanese. If you want to use the default Starter journal, click the Next button to continue.
Adding a Journal to the List If you have a journal, either from a previous installation, or one that someone has given to you in an archive file, you can add your journal to the list by typing the file path on your Traction server where the journal directory is located.
Once you have typed the path, click the +) button. If you do not type the correct path to a journal directory, Traction will report an error:
Page 93 of 281
Copyright © 2010 Traction Software, Inc.
If you get an error, check your path and try again. If you type the path correctly, your journal will be selected in the pull-down menu, and its description will appear in the Short Description field.
You can then click Next to continue.
Automatic Restart with Index Rebuild The server will now restart itself with the selected journal. While the server is restarting, it will also rebuild the index files on the Journal. This may take a few minutes. During this time you will see a spinning wheel and text that says "The server is restarting..." and the Next button will be greyed out.
Page 94 of 281
Copyright © 2010 Traction Software, Inc.
When the server has completed its restart and is back online, the wheel will stop spinning, the text will change, and the Next button will become solid:
When you click Next it will take you to the journal's Front Page or login form, depending on the journal selected and the credentials required for access.
Logging in to the Starter Journal If you select the Starter Journal, you can follow the instructions in the welcome article that has been posted.
Page 95 of 281
Copyright © 2010 Traction Software, Inc.
Page 96 of 281
Copyright © 2010 Traction Software, Inc.
If you wish to sign in as a server administrator, you can use the username admin, with no password, per the instructions in the welcome article. If you plan to continue using the Starter Journal, we recommend that you Personal Password after logging in. You can now begin using Traction, or continue reading the User Guide or Setup sections of the help.
Choosing and Configuring a User Directory Doc35: March 22, 2008 3:48 PM, Posted by Documentation Importer, Edited by Christopher Nuzum
Traction supports built-in user management, and can also connect to external Directory systems like Microsoft Active Directory and LDAP. When connected to outside systems, Traction can leverage single sign-on protocols like NTLM. The set of User Directories supported is extensible; Java plug-ins can be written to add support for new User Directories and authentication systems. By default, the list includes Traction's built-in user management types:
Clicking the New button opens up a window.
In this window, you can choose to fill in a template for Active Directory or LDAP.
Once you enter your site's information and save your configuration, your new configuration be listed in the User Directory pulldown, and you will be able to go back and edit its settings by selecting it and clicking the "Edit" button. For instructions on configuring Active Directory or LDAP, see the sections Configuring Active Directory Page 97 of 281
Copyright © 2010 Traction Software, Inc.
and Configuring LDAP. The table below explains the difference between the two supported built-in user management options. User Directory
Description
Journal, Access Control Lists (ACLs), Automatic Login for Visitor
Traction's default User Directory. If Visitor login is enabled via ACL, the first time people visit your server, they will see the content that is visible to Visitor. They can login to their own Traction account by clicking the "sign-in" link that appears on the page.
Journal, Access Control Lists (ACLs), Login Required for All Users
This variation always presents a login form to people who visit rather than showing content that is visible to visitor. If Visitor access is enabled via ACL, a "login as visitor" button appears on the sign-in screen.
Configuring Active Directory Doc40: March 22, 2008 3:49 PM, Posted by Documentation Importer, Edited by Christopher Nuzum
Configuring Traction to use Microsoft Active Directory This section explains how to configure Traction to work with Active Directory.
Open the Active Directory Editor Note: If you have configured Traction 3.5 to use Active Directory, you can continue to use your existing configuration (it will appear in the list of available User Directories), but you can not edit the settings using the web interface. To edit using the Active Directory configuration editor, you will need to use the editor to create a new profile for your Active Directory server.
For New Journals If you are creating a new Journal, click the New button underneath the User Directory selector on the Journal Setup interface.
For Existing Journals If you want to change the user directory for an existing Traction server, click the Modify User Directory button on Server Setup | General. Page 98 of 281
Copyright © 2010 Traction Software, Inc.
This takes you to the Select User Directory page. Page 99 of 281
Copyright © 2010 Traction Software, Inc.
Click the New button. This will bring up the User Directory editor. The top-right lists any User Directory profiles that you have created, and also lists blank templates that you can use to create a new profile.
Page 100 of 281
Copyright © 2010 Traction Software, Inc.
Select "Microsoft Active Directory Server" from the list. This brings up the Active Directory editor.
Page 101 of 281
Copyright © 2010 Traction Software, Inc.
Page 102 of 281
Copyright © 2010 Traction Software, Inc.
Overview This file is a User Directory template, which you can fill in. Once you save the template, it becomes a profile that you can edit, delete, test, and use. The file name of the template is listed under the template's type.
You can save your work as often as you like while you're doing this configuration. The save button is at the bottom of the page. You can name this configuration anything you like. As soon as you have made any changes, the Save button is enabled.
After you have saved, your profile appears in the pull-down menu at the top-right, and is selected:
The delete button is also enabled for profiles, allowing you to delete the current profile. If you click delete, you will be asked to confirm that you really want to delete the profile:
The file you are editing is displayed under the name you chose in the top-left:
Page 103 of 281
Copyright © 2010 Traction Software, Inc.
The filename listed underneath is for informational purposes only, since the Traction interface uses the actual name you chose.
Enter a Description This description is for your use in distinguishing between different profiles you may create.
General Settings Allow Visitor Login The default for Active Directory installations is No, which means that no Visitor login is allowed at all, regardless of ACL settings.
Force Visitor Login If you change Allow Visitor Login to Yes, you can then decide how Visitors login:
Page 104 of 281
Copyright © 2010 Traction Software, Inc.
Force Visitor Login
Behavior
No
When unauthenticated users first request a Traction page, they see content whose permissions make that content visible to Visitor.
Yes
When unauthenticated users first request a Traction page, they are taken to a login form that has a "Login as Visitor" button.
Active Directory Server Settings Enter the correct values for these settings from your Active Directory
Domain Controller
Default Domain The default domain setting lets you choose against which domains Traction will authenticate users. You can specify one or more domains (comma-separated) in this control.
When Traction prompts for a username and password, e.g. when using Active Directory but not NTLM, it will check each of the domains in this list for a matching username. If your organization uses a Global Catalog server and partitions users into multiple domains, you should enter the list of all domains from which a user might need to log in. Note: For Traction's multi-domain support to work correctly, usernames must be globally unique; if the user JSMITH is defined in domain A, JSMITH should not be a different user in domain B.
LDAP Search Base Enter the path of the sub-tree in LDAP where you would like to search for users. Important! The domain name corresponding to this path must be resolvable by name (either via DNS or a hosts file) from the machine on which the Traction server is installed. For example, if you specify the following Search Base: Page 105 of 281
Copyright © 2010 Traction Software, Inc.
You must be able to get a response by running a ping command, like this:
If your ping fails, you can add an entry to the hosts file (either /etc/hosts on Unix or the file listed below on Windows), like the following:
Page 106 of 281
Copyright © 2010 Traction Software, Inc.
LDAP Port Enter the port your Active Directory uses for LDAP connections. The default is 389, which appears in the template.
Authentication This refers to how the Traction server authenticates its connection with your LDAP server. Traction connects to LDAP in order to do User, Group, and Property (e.g. fullname, email address) lookups. There are two options: None and Simple.
If None is selected, Traction will attempt to make an anonymous connection to the Active Directory server. If your server allows anonymous connections to perform the necessary lookups, this may suffice for you. Most Active Directory servers require authentication. If your server requires authentication, select "Simple". When you select Simple, Account and Password fields open up underneath. Page 107 of 281
Copyright © 2010 Traction Software, Inc.
Important! The account you specify must be domain-qualified, as shown in the example. Just the name of an account does not suffice, even if you have specified a default domain. Note: The password you enter will be stored using strong secret-key encryption in a Traction configuration file. VERY IMPORTANT: If possible, the password you specify should be set not to expire. Otherwise, when the password expires, any users authenticated via Active Directory will not be able to log in to Traction. If you can not set the password not to expire, we recommend that you make a note of the password expiration date and change the Traction password followed by the system password before that date.
Advanced Settings Login Method Most customers using Active Directory use NTLM, which logs in users automatically, creating a Traction account with the same UserID as their Windows login the first time they visit Traction. Using NTLM, users never need to enter their Traction username or password, and Traction is never made aware of the user's password; instead it gets a hash from the login manager that it verifies with Active Directory.
Important Security Note: Realms and Cookies require users to enter their passwords when they visit Traction, and differ in how the login is maintained. Cookies allows the login to be maintained using either persistent or session cookies stored in the web browser, depending on whether the administrator enables -- and the user selects -- a "Remember me" checkbox on the login form. When the user logs in using realms, the password is sent uuencoded, which is considered cleartext for security purposes. Using cookies, the password is encrypted and base-64 encoded. For this reason, if you elect to use realms or cookies, we urge you to use HTTPS rather than HTTP. HTTPS is easy to configure in Traction; see the instructions in this help document. Once the password has been received by Traction and authenticated by Active Directory, when using cookies, the login session is maintained using an encrypted cookie. If realms is used, the original login information is passed back and forth with each request. Since NTLM never reveals the user's password to Traction, we consider NTLM to be more secure than cookies or Page 108 of 281
Copyright © 2010 Traction Software, Inc.
realms.
NTLM Options If NTLM is enabled, you can choose whether or not to allow Basic (realms) authentication for browsers that do not support NTLM.
If you elect to Enable Basic Authentication, it will only be supported on HTTPS connections, unless you also enable the next option:
Note that the option to enable Insecure Basic Authentication is only available if you have already selected that you want to enable basic authentication.
Enable Traction User Management This option lets you define users in Traction that do not exist in your Active Directory server, for example outside consultants or customers.
Note: This option is only available when you select Cookies or Realms; it is not supported in conjunction with NTLM. Page 109 of 281
Copyright © 2010 Traction Software, Inc.
Change Password Message You can override the default message that users will see if they arrive at a page in Traction that, with some user directories, would allow them to change their password.
Additional Options In rare cases, Traction support may suggest that you add text in this field to access very unusual configuration settings.
Principal Cache Settings Traction can optionally cache certain information in order to improve performance and to reduce the load on your Active Directory server.
Group Membership Search
For Active Directory, this setting should be set to Direct.
Enable Principal Cache
Page 110 of 281
Copyright © 2010 Traction Software, Inc.
We generally recommend that you set this to yes. Caching reduces the time it takes to compute permissions, reduces load on your directory server, for systems with heavy usage it may reduce network bandwidth, and it generally improves performance. If your Active Directory server is especially large (generally speaking, hundreds of thousands of users or more), Traction may require significant memory resources to maintain the principal cache. If your server is exceptionally fast and you have plenty of CPU available, you may not notice appreciable benefit from the cache. In these scenarios, disabling the cache may be appropriate.
Cache Update Time
Often directory servers are synchronized with each other (e.g. a branch server synchronized with a remote server) at a specific time of day. Normally, you'll want Traction's cache to be updated after the synchronization completes. Enter the local time when you would like to make sure the cache is repopulated.
Cache Update Interval
This setting governs how frequently information in the cache should be re-fetched from the directory server. This is done automatically; the updated information replaces the existing information in the cache before it expires. That way, the information in the cache is always no older than the specified interval. The time it takes to update the cache depends on the size of the directory. We have seen ranges from 20 seconds to 20 minutes. For larger directories, less frequent updates may be appropriate. If a scenario arises where it's important to update the cache immediately, press the "Clear Caches" button in Server Setup to flush the cache and force the information to be re-requested from the directory server.
Testing Your Setup When you have finished entering all the settings, save your changes. After you click the Save button, the page will reload, and the Test button will become enabled.
Page 111 of 281
Copyright © 2010 Traction Software, Inc.
Click the test button to launch the Test User Directory window.
Page 112 of 281
Copyright © 2010 Traction Software, Inc.
Page 113 of 281
Copyright © 2010 Traction Software, Inc.
Test Login To verify that users can login using the profile you have created, enter a username and password and press the Test Login button. Important! Note: The username will be tested against all the domains listed in the Default Domain property. If you want to test a user in a different domain than those listed, or in a specific domain, you can enter the user's domain-qualified username, e.g. THEDOMAIN\username.
If the username and password are verified by Active Directory, Traction will report Login Successful.
If the password is not correct, Traction will report:
Page 114 of 281
Copyright © 2010 Traction Software, Inc.
If the username can not be found, Traction will report:
If the login test does not succeed, go back and check your settings and make sure that you can ping the Active Directory server by its DNS name from the computer running Traction.
Test Lookup Once you have the Login test working, you can lookup a user by typing any portion of the username or User ID:
Page 115 of 281
Copyright © 2010 Traction Software, Inc.
Clicking lookup should return all matches in your Active Directory.
Page 116 of 281
Copyright © 2010 Traction Software, Inc.
If you just click the Test Lookup button, Traction will warn you that you will return all hits.
If you select OK, all hits will be returned. Depending on how many entries you have in your server, this may take a long time and be slow to display.
Page 117 of 281
Copyright © 2010 Traction Software, Inc.
Inspecting Account Details You can also get details for any account by selecting the account and clicking the Show Details link:
This will pop up a window with the details for that user:
Page 118 of 281
Copyright © 2010 Traction Software, Inc.
Note: Traction uses the user's Active Directory GUID to maintain the mapping between the Traction user and the Windows user.
Troubleshooting If you run into trouble and need more information to understand what might be going on, you can turn on debug logging and use the Log File Viewer to diagnose the problem. To learn more about this, see the section Troubleshooting Using the Log File Viewer.
Saving and Continuing Once you are satisfied that both the Login and Lookup Tests are working, you can close the test window. You can also click the Close window button on the Configure User Directory page:
Page 119 of 281
Copyright © 2010 Traction Software, Inc.
This should reveal the page you launched from, either Journal Setup or Modify user Directory, with your new profile selected:
You can now proceed with Creating a New Journal, or continue with the process of Changing User Directories.
Configuring LDAP Doc41: March 22, 2008 3:50 PM, Posted by Documentation Importer
Configuring Traction to use LDAP This section explains how to configure Traction to work with LDAP servers like Novell eDirectory.
Open the LDAP For New Journals If you are creating a new Journal, click the New button underneath the User Directory selector on the Journal Setup interface.
For Existing Journals If you want to change the user directory for an existing Traction server, click the Modify User Directory button on Server Setup | General.
Page 120 of 281
Copyright © 2010 Traction Software, Inc.
This takes you to the Select User Directory page. Page 121 of 281
Copyright © 2010 Traction Software, Inc.
Click the New button. This will bring up the User Directory editor. The top-right lists any User Directory profiles that you have created, and also lists blank templates that you can use to create a new profile.
Page 122 of 281
Copyright © 2010 Traction Software, Inc.
Page 123 of 281
Copyright © 2010 Traction Software, Inc.
Overview This file is a User Directory template, which you can fill in. Once you save the template, it becomes a profile that you can edit, delete, test, and use. The file name of the template is listed under the template's type.
You can save your work as often as you like while you're doing this configuration. The save button is at the bottom of the page. You can name this configuration anything you like. As soon as you have made any changes, the Save button is enabled.
After you have saved, your profile appears in the pulldown menu at the top-right, and is selected:
The delete button is also enabled for profiles, allowing you to delete the current profile. If you click delete, you will be asked to confirm that you really want to delete the profile:
The file you are editing is displayed under the name you chose in the top-left: Page 124 of 281
Copyright © 2010 Traction Software, Inc.
The filename listed underneath is for informational purposes only, since the Traction interface uses the actual name you chose.
Enter a Description This description is for your use in distinguishing between different profiles you may create.
General Settings Allow Visitor Login The default for LDAP installations is No, which means that no Visitor login is allowed at all, regardless of ACL settings.
Force Visitor Login If you change Allow Visitor Login to Yes, you can then decide how Visitors login:
Page 125 of 281
Copyright © 2010 Traction Software, Inc.
Force Visitor Login
Behavior
No
When unauthenticated users first request a Traction page, they see content whose permissions make that content visible to Visitor.
Yes
When unauthenticated users first request a Traction page, they are taken to a login form that has a "Login as Visitor" button.
LDAP Server Settings Enter the correct values for these settings from your Active Directory
Server URL The LDAP Server URL contains most of the information that Traction requires to do LDAP lookups.
Traction supports normal LDAP and (secure ldap). By appending : and a port number, you can specify a different port to contact. The middle of the URL is the tree in your LDAP server to search. Important! If you want to use LDAPS, your LDAP server must be configured to work with LDAPS. Like HTTPS, LDAPS uses digital certificates to verify the identity of the server. Your LDAPS server will have a certificate installed in it, and when a client like Traction attempts to contact your server, the server will present its certificate to Traction. If your certificate has been signed by a top-level Certificate Authority (CA), Traction will make the connection. Otherwise, Traction will check its built-in store of trusted certificates to see if it recognizes your server. If it does, it will continue with the connection. If not, Traction will remember your server's certificate in its list of "untrusted certificates". You can use the Trust Manager to move the certificate to the list of "trusted certificates", or you can import your server's .pem or .cer file directly into Traction's list of trusted certificates. To get to the Trust Manager, you can click the "Click here to manage trusted certificates" link in the description above the LDAP URL. To learn more about the trust manager, see Using the Trust Manager. The recommended sequence for setting up LDAPS is covered below.
Authentication This refers to how the Traction server authenticates its connection with your LDAP server. There are two options: None and Simple.
Page 126 of 281
Copyright © 2010 Traction Software, Inc.
If None is selected, Traction will attempt to make an anonymous connection to the LDAP server. If your server allows anonymous connections to perform the necessary lookups, this may suffice for you. Many LDAP servers require authentication. If your server requires authentication, select "Simple". When you select Simple, Account and Password fields open up underneath.
Important! The account you specify must be the distinguished name (DN), as shown in the example. Just a userid does not suffice. Note: The password you enter will be stored using strong secret-key encryption in a Traction configuration file. VERY IMPORTANT: If possible, the password you specify should be set not to expire. Otherwise, when the password expires, any users authenticated via LDAP will not be able to login. If you can not set the password not to expire, we recommend that you make a note of the password expiration date and change the Traction password followed by the system password before that date.
Advanced Settings Enable Traction User Management This option lets you define users in Traction that do not exist in your LDAP server, for example outside consultants or customers.
Page 127 of 281
Copyright © 2010 Traction Software, Inc.
Change Password Message You can override the default message that users will see if they arrive at a page in Traction that, with some user directories, would allow them to change their password.
Verify LDAP Password As This setting lets you control whether the user's password is confirmed via a lookup by an administrator or an attempt to bind as the user with the supplied password.
LDAP Schema Mapping and LDAP Searches LDAP schemas vary from company to company, but most LDAP schemas represent the information that is used by Traction. This section lets you specify the attributes used in your LDAP schema and the searches that Traction should use to do the lookups it performs. By default the next two sections are shown collapsed on the setup page.
You can click the expand/collapse control to show and hide the sections.
LDAP Schema Mapping When you click the expand button, you can edit the attributes used for each type of lookup. Page 128 of 281
Copyright © 2010 Traction Software, Inc.
The defaults listed are typical for an out-of-the-box NDS server. You can change the default that is listed, or click the checkbox to reset to the default when you press the save button. Starting in version 3.6.1.5, Traction supports dynamic LDAP groups and indirect group membership searching. Dynamic groups are expressed in LDAP using a query instead of placing individual members in a group. Indirect search means checking the group for its members instead of checking a user for its groups (direct searching). Some LDAP servers require indirect searching for determining group membership.
Page 129 of 281
Copyright © 2010 Traction Software, Inc.
LDAP Searches Expanding the LDAP Searches control lets you modify the LDAP query that is used to look up information in your LDAP server. You will need to change the search specified if: 1. You change the schema mapping, as described above. In this case, you will need to edit the search expression to include the actual attribute your server uses. 2. You need to do a different lookup to return the indicated result set, e.g. you want email completion to match uid in addition to mail and fullname. In the queries below {0} is substituted by the search term as indicated in each description..
Page 130 of 281
Copyright © 2010 Traction Software, Inc.
Page 131 of 281
Copyright © 2010 Traction Software, Inc.
Principal Cache Settings Traction can optionally cache certain information in order to improve performance and reduce the load on your LDAP server.
Group Membership Search
If your LDAP server supports direct lookups, where the user object has a list of the groups it belongs to, we recommend that you choose direct. If the directory server can only return the members of a group, and can not return the list of groups of which a user is a member, you will need to select Indirect.
Enable Principal Cache
We generally recommend that you set this to yes. Caching reduces the time it takes to compute permissions, reduces load on your directory server, for systems with heavy usage it may reduce network bandwidth, and it generally improves performance. If your LDAP server is especially large (generally speaking, hundreds of thousands of users or more), Traction may require significant memory resources to maintain the principal cache. If your server is exceptionally fast and you have plenty of CPU available, you may not notice appreciable benefit from the cache. In these scenarios, disabling the cache may be appropriate.
Cache Update Time
Often directory servers are synchronized with each other (e.g. a branch server synchronized with a remote server) at a specific time of day. Normally, you'll want Traction's cache to be updated after the synchronization completes. Enter the local time when you would like to make sure the cache is repopulated.
Cache Update Interval
Page 132 of 281
Copyright © 2010 Traction Software, Inc.
This setting governs how frequently information in the cache should be re-fetched from the directory server. This is done automatically; the updated information replaces the existing information in the cache before it expires. That way, the information in the cache is always no older than the specified interval. The time it takes to update the cache depends on the size of the directory. We have seen ranges from 20 seconds to 20 minutes. For larger directories, less frequent updates may be appropriate. If a scenario arises where it's important to update the cache immediately, press the "Clear Caches" button in Server Setup to flush the cache and force the information to be re-requested from the directory server.
Testing Your Setup Whenever you want to test your current settings, save your changes. After you click the Save button, the page will reload, and the Test button will become enabled.
Click the test button to launch the Test User Directory window.
Page 133 of 281
Copyright © 2010 Traction Software, Inc.
Page 134 of 281
Copyright © 2010 Traction Software, Inc.
Test Login To verify that users can login using the profile you have created, enter a username and password and press the Test Login button.
If the username and password are verified by your LDAP server, Traction will report Login Successful.
If the password is not correct or the username can not be found in LDAP, Traction will report:
Page 135 of 281
Copyright © 2010 Traction Software, Inc.
Test Lookup Once you have the Login test working, you can lookup a user by typing any portion of the username or User ID:
Clicking lookup should return all matches in your Active Directory.
Page 136 of 281
Copyright © 2010 Traction Software, Inc.
If you just click the Test Lookup button, Traction will warn you that you will return all hits.
If you select OK, all hits will be returned. Depending on how many entries you have in your server, this may take a long time and be slow to display.
Page 137 of 281
Copyright © 2010 Traction Software, Inc.
You can also get details for any account by selecting the account and clicking the Show Details link:
This will pop up a window with the details for that user:
Page 138 of 281
Copyright © 2010 Traction Software, Inc.
Troubleshooting If you run into trouble and need more information to understand what might be going on, you can turn on debug logging and use the Log File Viewer to diagnose the problem. To learn more about this, see the section Troubleshooting Using the Log File Viewer.
Saving and Continuing Once you are satisfied that both the Login and Lookup Tests are working, you can close the test window. You can also click the Close window button on the Configure User Directory page:
Page 139 of 281
Copyright © 2010 Traction Software, Inc.
This should reveal the page you launched from, either Journal Setup or Modify user Directory, with your new profile selected:
You can now proceed with Creating a New Journal, or continue with the process of Changing User Directories.
Setting up LDAPS
Configuring Multiple LDAP or Active Directory Servers Doc42: March 22, 2008 3:50 PM, Posted by Documentation Importer
In some cases it might be necessary to check multiple LDAP or Active Directory servers to locate and authenticate all of the users. As some searches will require looking in all of the LDAP servers, where possible you should consolidate the users into a single directory or rely on replication capabilities provided by your directory. Using the Additional Settings field in the Advanced Settings section of the configuration, add the following settings for additional directories. Do not repeat the original configuration here, just add additional ones. # Server ldap0_server=192.168.0.15 ldap0_root=DC=traction,DC=ads ldap0_port=389 or ldap0_url=ldap://192.168.0.15:389/DC=traction,DC=ads # Login ldap0_authentication=[none/simple] ldap0_login=DOMAIN\Username
Page 140 of 281
Copyright © 2010 Traction Software, Inc.
ldap0_password=password For each additional server, increment the number of the prefix (ldap1_server= ...). If any value is unspecified, it will default to the value provided with the ldap_ prefix. For example, if ldap_authentication=simple and ldap0_authentication= is not specified, ldap0 will use simple authentication. It might help to look at the generated configuration file. To open the generated file, click the link in the upper left portion of the configuration dialog, below the title of the configuration.
Changing User Directories and Migrating Principals Doc28: March 22, 2008 3:47 PM, Posted by Documentation Importer
This chapter describes how you can change the User Directory used to manage users. For an overview of User Directories, see Choosing and Configuring a User Directory.
Background and Terminology Each user known to Traction has a profile maintained by Traction. This profile is identified by the Traction User ID. User ID's are numbers assigned by the Traction server. The user's username is an attribute associated with the userid; usernames are used to log in. Additionally, each user has a Principal. Permissions are assigned to Principals using Access Control Lists (ACL's). The Principal for a user identifies the user in Traction's own built-in User Directory, or in LDAP or Active Directory. Principals for the different directory types look different. For example, Active Directory principals refer to the user's GUID, while LDAP Principals generally refer to the user's Common Name (CN). Principals for users managed by Traction refer to the Traction User ID. Traction users with Administer Server permissions can change the Principal associated with users. When a User's Principal changes, the system used to manage that user changes. Users with Active Directory Principals are Authenticated using Active Directory, and so on. When changing Principals, Traction automatically updates all references to that Principal in existing ACL's, so that a user's permissions do not change when their Principal is switched to a different system. Traction provides two interfaces for changing principals: a batch interface, and an interface for modifying individual users. We refer to the process of switching from one Directory system to another migration; during this process, users are assigned new principals based on their identity in the other system. Traction supports migrating principals from any known User Directory to any other known User Directory, e.g. from Traction to Active Directory, Active Directory to LDAP, LDAP to Traction, and so on. Traction also supports hybrid User Directories, where different users may be authenticated by different Directories. The most common system is where some users (e.g. authenticated search engines, external contractors, clients, or customers) do not exist inside the corporate Directory and are managed via Traction, while most employees are managed using the Directory. We will present an example of migrating to Active Directory, but the process is the same for migration to any User Directory. Page 141 of 281
Copyright © 2010 Traction Software, Inc.
Migrating from Built-In User Management to Active Directory First, go to Server Setup | General.
Click the Modify User Directory button in the Current Journal section.
Select the User Directory to which you wish to migrate. If necessary, follow the instructions in the chapter Choosing and Configuring a User Directory to set up and test the target User Directory. Page 142 of 281
Copyright © 2010 Traction Software, Inc.
Make sure that the Migrate Principals checkbox is checked, then press Next.
The next page may take some time to load, while the Traction server attempts to contact the target User Directory and tries to automatically determine the new Principal for each user. Page 143 of 281
Copyright © 2010 Traction Software, Inc.
When Traction has completed this process, it will display a page that shows its best guess for the new Principal for each user. The users for whom Traction was able to find a match will be displayed in yellow.
You can now manually map any users who were not matched, or fix the mappings for any users that were guessed incorrectly, using the Lookup button. The lookup button uses the same lookup technique as in Page 144 of 281
Copyright © 2010 Traction Software, Inc.
testing a User Directory. You can type part of the user's userid, fullname, or email address, and press Lookup:
This will pop up a dialog with a list of matching names. You can select the correct match, or enter another name to query inside the lookup. When you have identified the correct user, press OK.
The fields in the main page will be filled in with the result of the lookup.
If you wish to see the complete details, you can click the Show Details link.
Page 145 of 281
Copyright © 2010 Traction Software, Inc.
This will pop a dialog showing detailed information for the selected user.
You can repeat this process as necessary to make sure that as many of the mappings as possible are correct. If you have a few you are uncertain about, you can modify them individually later in Personal Setup. When you are ready, press the Finish button.
Traction will warn you that the system must be restarted.
Page 146 of 281
Copyright © 2010 Traction Software, Inc.
When you press OK, you will see the restart message.
When the migration has completed and the server is back online, Traction will report:
You can press the home link to log in. You may be required to log in using your Active Directory credentials at this point. If you migrated all users, you should now be finished. Page 147 of 281
Copyright © 2010 Traction Software, Inc.
If you left any users unmigrated, you can follow the instructions below to modify individual accounts.
Modifying Principals in Personal Setup Users with Administer Server permissions can change the Principal associated with a Traction user via the Modify Principal link on the Personal Setup | Permissions tab for that user.
This will pop up a Modify Principal dialog; you can use the Lookup control to search for the matching user.
Page 148 of 281
Copyright © 2010 Traction Software, Inc.
After you have found the corresponding user in the Directory, press Apply, and then Close.
Page 149 of 281
Copyright © 2010 Traction Software, Inc.
If you subsequently reload the permissions page, you will see that the Principal has been updated.
Page 150 of 281
Copyright © 2010 Traction Software, Inc.
Troubleshooting Using the Log File Viewer Doc305: March 22, 2008 4:24 PM, Posted by Documentation Importer
You may enter what looks like correct configuration information, but your test lookup may return an error message like:
But you are the Server Administrator. Traction has a number of built-in diagnostic and troubleshooting tools that can help you track down the problem.
Page 151 of 281
Copyright © 2010 Traction Software, Inc.
At the bottom of the Test User Directory window is a link to the Server Setup page that lets you configure debug logging.
Turning on Debug Logging Clicking this link will pop up the Server Setup | Server Files page.
Page 152 of 281
Copyright © 2010 Traction Software, Inc.
On this page, you can turn on debug logging for many different Traction functions. To turn on debug logging, fir make sure that the "log debugging information" checkbox is checked:
Next, decide what debug information you want to log and check the corresponding checkboxes. For debugging LDAP/Active Directory issues, we suggest the ones indicated below. Page 153 of 281
Copyright © 2010 Traction Software, Inc.
Once you have made your selections, click the apply button at the bottom of the page. When your changes have been applied, the Apply button will become grey, indicating there are no pending changes.
Using the Log File Viewer Click the "Open Log File Viewer" button on the Test User Directory to open the viewer.
Page 154 of 281
Copyright © 2010 Traction Software, Inc.
The viewer pops open in a new window.
This viewer has a number of controls that let you explore log files. Page 155 of 281
Copyright © 2010 Traction Software, Inc.
1. Name of the file being inspected. Clicking this link opens the file in a new window. 2. File contents. Only n lines are shown, where n is specifid in control 4. 3. Checkbox to turn on/off wrapping of long lines. 4. Controls how many lines to read at a time. 5. Same as 1. 6. Position indicator, shows the location and volume of the file being shown in the viewer. Works similarly to a scroll bar, but you can not drag the thumb. 7. Rewinds to show the first chunk of the file. 8. Shows the previous chunk. 9. Clicking here is the same as clicking 8. 10. Thumb indicator, Its width indicates the percentage of the file (in characters, not lines) represented by the current view. 11. Clicking here shows the next chunk. 12. Next chunk button. 13. Shows the last n lines of the file, counting from the end. Clicking this repeatedly lets you watch what is currently happening. 14. Search field. Lets you specify a simple text string to look for. 15. Checkbox to govern whether case affects search results. 16. Button to jump to the first line that matches the search. A few lines of context are shown before the search match. 17. Button to jump to the previous search result. 18. Button to jump to the next search result. 19. Button to jump to the last search result in the file. Starts at the end of the file and searches backward. 20. Button to close the viewer window. Using these controls, you can diagnose problems by looking at current logfile output. One good thing to look for is Exceptions:
Page 156 of 281
Copyright © 2010 Traction Software, Inc.
When you click "Find Last", you will jump to the last matching line.
In this case, we see that the problem was that the connection timed out. Problem
Cause
Solution
Page 157 of 281
Copyright © 2010 Traction Software, Inc.
java.net.ConnectException: Connection timed out
Error in Active Directory Domain controller IP address or LDAP URL
Correct the IP address or LDAP URL on the configure user directory page.
DNS lookup of hostname See the instructions related to corresponding to the search base Configuring Active Directory. can't be resolved on computer Traction is running on. Directory server not running or can't be reached LDAP connection timed out
java.net.UnknownHostException
Make sure that another program that requires the directory server is able to contact it. Check LDAP Server not running or can't network connections and firewall settings. be reached The Active Directory search base This exception will include the may have an error. name of the hostname it is trying to resolve. E.g. in the case of the exception: java.net.UnknownHostException: vm.ajm.tractionsoftware.comm We can see that there is an extra "m" in .com.
Correct the LDAP search base. java.net.ConnectException: Connection refused: connect
You may have specified the Cross-check the port you have wrong port for the LDAP or Active specified versus the one your Directory server server runs on and correct any discrepancies.
javax.naming.CommunicationException: You may have specified the port Make sure that the port specified Request: 1 cancelled of a different type of server, e.g. a is the port where your directory web server or mail server. server accepts connections. javax.naming.NamingException: Authentication is required, but [LDAP: error code 1 - 00000000: you have set Authentication Type LdapErr: DSID-0C0905FF, to None comment: In order to perform this
Set authentication to "simple", and fill in the username and password fields with an account with access to the directory Page 158 of 281
Copyright © 2010 Traction Software, Inc.
operation a successful bind must be completed on the connection., data 0, vece]; remaining name ''
server.
Login fails Lookups return no matches javax.naming.AuthenticationException: Your simple authentication [LDAP: error code 32 - NDS credentials are incorrect error: no such entry (-601)]
Make sure that you have specified valid username and password. You may wish to check them with another program, like JXplorer.
javax.naming.InvalidNameException: You may have typed an account Make sure you specify a DN. [LDAP: error code 34 - Invalid DN name, such as "Admin" instead of Syntax] a DN like "cn=Admin,o=Traction" into the Account field under Simple Authentication javax.naming.AuthenticationException: You likely entered your password Make sure you have the correct [LDAP: error code 49 - NDS incorrectly in the password, and verify that no error: failed authentication (-669)] sticky modifier keys (e.g. caps lock, num lock) are affecting what you're typing. Try typing the password in another window to make sure it looks correct.
First Login with Built-In User Directory Doc120: March 22, 2008 4:03 PM, Posted by Documentation Importer
If you chose Traction's built-in User Directory If you specified a built-in User Directory and you have a login screen, sign in as one of the users you created during Journal Setup, or click the "Login as Visitor" button (if present) to go to the front page.
Page 159 of 281
Copyright © 2010 Traction Software, Inc.
This should take you to the home page.
Page 160 of 281
Copyright © 2010 Traction Software, Inc.
First LDAP Login Doc116: March 22, 2008 4:02 PM, Posted by Documentation Importer
If you chose LDAP With Visitor Access If you chose to enable Visitor access, instead of a login screen, you should be taken directly to the front page.
Page 161 of 281
Copyright © 2010 Traction Software, Inc.
In order to create your first profile, you should now sign in as an LDAP user. Click the Sign In link:
Page 162 of 281
Copyright © 2010 Traction Software, Inc.
This will take you to the sign-in form. Continue with the instructions below.
Without Visitor Access If you set your User Directory to LDAP without visitor access, or have clicked the Sign In link, enter your LDAP username and password into the login form.
A Traction profile is created for you when you first log in. This should take you to a front page that looks like this:
Page 163 of 281
Copyright © 2010 Traction Software, Inc.
If your account was created correctly, you should see a sign out link in the right sidebar.
Page 164 of 281
Copyright © 2010 Traction Software, Inc.
First Active Directory Login Doc115: March 22, 2008 4:02 PM, Posted by Documentation Importer
You should start out directly at the front page.
However, depending on who you are logged in to Windows as, you may instead see an error like one of the following:
Page 165 of 281
Copyright © 2010 Traction Software, Inc.
This indicates that the Windows account you are logged into has not been authenticated by your Active Directory server. This usually happens when you install Traction as a local machine Administrator instead of logging in as a domain user. At this point, in order to continue configuring Traction, you need to log in to Windows as a domain user. If you then visit Traction, you should see the front page as described above.
How do ACLs Work Doc133: March 22, 2008 4:04 PM, Posted by Documentation Importer
Access Control Lists define permissions for users and groups. You can assign permissions settings for each permission (Login, Administer Server, Edit Stylesheets, etc.) to users and groups.
Allow vs. Deny In setting up permissions, you can allow or deny each permission to each user or group. Any given user inherits the sum of their Allow permissions (assigned directly or through a group) minus any permission which has been denied. If a permission is not explicitly allowed, it is not granted. Deny always dominates over allow. For example, you can specify "Everyone allow login" and "Visitor deny login". ("Visitor" is included in the default "Everyone" group). This means that everyone but Visitors will be allowed to log in. Important! Deny is very powerful, and can get you into trouble. You can lock everyone, yourself included, out of your journal by adding an "Everyone deny login" permission to the Server Access Control List. You can make it impossible for anyone to access server setup (where ACLs are defined) if you apply an Page 166 of 281
Copyright © 2010 Traction Software, Inc.
"Everyone deny Administer Server" rule. If you do either of these things, you can contact Traction Software support for a special Owner license. This license, which is keyed to your journal, enables a special account, called Owner. Logging in as Owner with the provided Owner password will let you fix the ACLs so you can recover access. Traction will warn you before letting you deny permissions. Please read the warnings, and think twice before clicking the apply button.
Setting Login Permissions Doc261: March 22, 2008 4:19 PM, Posted by Documentation Importer
About Login Permissions In a new journal, a default set of permissions is defined. Depending on the User Directory you selected, you may have a single account designated as a member of the Server Administrator's group, or the group Everyone may be listed as a Server Administrator. This section explains how to limit login permission to only specific users or groups.
Who should I let log in? Visitors One important question is whether you want unauthenticated users to be allowed to see content marked visible to Visitor in your Traction journal. If so, you should allow Visitor to login. If you do not want unauthenticated users or robots (like search engines) accessing your journal at all (i.e. you want everyone to have to log in with his, her, or its own profile) you can deny Visitor login.
Members of which LDAP or Active Directory Groups If you are connected to an external directory, there may be many more people in that directory than you have purchased Traction licenses for. If more people log in (and get Traction profiles) than your license allows for, your server will go into a read-only state until you deactivate enough accounts to bring it down to the limit (or purchase additional accounts). The Login permission lets you control the users for whom named accounts should be created. Others can access Traction as Visitor, if you allow it.
Everyone If you are using Traction's built-in directory, you may find it most convenient to just allow Everyone to log in (denying Visitor if you like).
Page 167 of 281
Copyright © 2010 Traction Software, Inc.
Using the Server ACL Editor Intro Doc319: March 22, 2008 4:26 PM, Posted by Documentation Importer
Overview of the Server ACL Editor The Server ACL Editor allows you to grant the following permissions to any user or group, whether Page 168 of 281
Copyright © 2010 Traction Software, Inc.
defined in Traction or in an external directory: Permission
Description
Login
If login is allowed, the user is (or group members are) allowed to log in to Traction. For users defined in external directories, a Traction profile is created for each user the first time that user logs in. If login is denied, the named user or group will not be allowed to login. This permission should be granted to everyone that you want to have access to a Traction profile and not granted or denied to everyone else.
Server Setup
Controls who is allowed to access the Server Setup views. Should only be granted to the people responsible for maintaining your Traction installation.
Edit Stylesheets
Governs access to Traction's built-in stylesheet editor, which allows users to customize the color scheme and layout of the default Ocean skin. This permission should generally be granted to Everyone, except in cases where you want to prevent users from customizing stylesheets.
Modify /pub Folder
Controls who is allowed to add, remove, or change files stored in Traction's /pub folder. The contents of the /pub folder are visible to everyone without requiring login, but only users with this permission can control its contents. Should only be granted to the people responsible for maintaining your Traction installation, and people with an established need to post non-permissioned content (for example, Flash or Quicktime movies referred to in Traction articles) for the general public.
Modify System Folders
System Folders refer to folders where Traction's configuration files are stored. By enabling users to Page 169 of 281
Copyright © 2010 Traction Software, Inc.
modify these folders, certain configuration changes, such as uploading skin files, can be accomplished remotely. Should only be granted to the people responsible for maintaining your Traction installation. Modify Account
If allowed, user is allowed to edit preferences and other account settings. Otherwise, the My Account link does not appear and access to the pages are not granted. This permission should generally be granted to Everyone.
Access Address Book
Governs access to functions that may disclose a list of users. If allowed, the covered users will be able to access the following functions: Visibility, which shows what users can read a given article once it has been posted. Email Address Completion; Traction's outgoing mail forms do completion against Traction's built-in users and against users with email addresses listed in Active Directory. Email address completion is also enabled on the Advanced Search form. We recommend that this permission be granted to internal users, but not to Visitor or guests (like customers) in order to prevent disclosure of email addresses.
Send Diagnostic Feedback
Controls what information is included in the feedback form that appears at the bottom of the page or when an error is encountered. If allowed, Full feedback is sent. Otherwise, only Brief feedback is sent. Click the permission name to see an example of Full and Brief details.
Page 170 of 281
Copyright © 2010 Traction Software, Inc.
For private applications, we recommend that this permission be granted to Everyone. For applications where Traction serves the general internet community, we recommend denying Visitor this permission, in order to prevent hackers from determining the type and version of your host operating system. Email Out
Controls who is allowed to email articles out of Traction using the Email Articles feature. Note that, naturally, there is no way to prevent users from copying content from Traction into their email clients.
Page 171 of 281
Copyright © 2010 Traction Software, Inc.
Export
Controls who is allowed to export article content to PDF, WordML, etc. using the Export Articles feature.
Tour of the ACL Editor The first section lists the users and groups for whom permissions have been configured. One user or group at a time can be selected. The permissions for the selected user or group appear in the Permissions panel underneath. Page 172 of 281
Copyright © 2010 Traction Software, Inc.
When a user or group is selected, clicking the Show Details link in the top-right will pop up a window showing the administrative details for the user. The details window for groups shows the group membership. You can remove the selected user or group by clicking the remove button. You can add a user or group by clicking the corresponding add button. The Permissions list has three columns. The first names the permission. The next two columns have checkboxes that either allow or deny the permission. Only one of these can be checked at a time. If neither is checked, the permission defaults to not granted, except during failsafe mode: if no Login permissions have been defined, Everyone is allowed to login, and if no Administer Server permissions have been defined, Everyone can administer the server. The Effective Permissions link lets you specify a user or group and show the result of applying the entire Access Control List to that user. This can be used to preview permissions for users who have not yet logged in and for whom no Traction profile yet exists. After modifying the page, the Reset and Apply buttons become activated and the Effective Permissions button becomes deactivated. Clicking Reset throws away all edits you have made and displays the active ACL. Clicking Apply activates the ACL and re-enables the Effective Permissions button.
Sample User Details Window
Page 173 of 281
Copyright © 2010 Traction Software, Inc.
\
Sample Group Details Window
Page 174 of 281
Copyright © 2010 Traction Software, Inc.
Sample Effective Permissions Window If a permission has been granted, it shows with a green checkbox. If denied, it shows with a red X. If the permission has been neither granted nor denied, the box is blank, and the permission is not granted.
Page 175 of 281
Copyright © 2010 Traction Software, Inc.
Getting to the Server ACL Editor Doc128: March 22, 2008 4:03 PM, Posted by Documentation Importer
Next we will create the permissions that define who is allowed to access and administer your server. In order to do this, we will need to use the Server ACL editor. This section describes how to get there. Page 176 of 281
Copyright © 2010 Traction Software, Inc.
First, click the link to Server Setup in the right sidebar.
This takes you to the Sever Setup | General page. Next, click "People" to move to the People tab.
This will take you to the people tab. Important! You should see at least one user listed here. If not, you probably forgot to sign in and are running as Visitor. If so, go back and sign in to create your own profile before proceeding. Next, click the Access Control List button.
Page 177 of 281
Copyright © 2010 Traction Software, Inc.
This will pop up the Server Access Control List editor window.
Page 178 of 281
Copyright © 2010 Traction Software, Inc.
Choosing Users Doc34: March 22, 2008 3:48 PM, Posted by Documentation Importer
To assign permissions to a user, click the Add User button.
Page 179 of 281
Copyright © 2010 Traction Software, Inc.
This will pop the lookup window.
Page 180 of 281
Copyright © 2010 Traction Software, Inc.
You can type a few characters of the name, email address, or username of the person you are looking for and press the lookup button to return a list of all matching users. If you press the lookup button without typing anything, Traction will warn you that it is going to return a list of all users in your directory:
Page 181 of 281
Copyright © 2010 Traction Software, Inc.
We recommend only pressing OK at this point only if you have fewer than a thousand entries in your directory server. Pressing OK on very large servers may make your browser unresponsive. The results of a lookup are listed in a pop-up window. Users with a Traction profile are listed first, followed by users defined in an external directory server.
Click the name of the user you wish to add and press the OK button. The New User ACL Entry dialog will now show the user you selected.
Page 182 of 281
Copyright © 2010 Traction Software, Inc.
When you press OK, the user will be listed in the Access Control List:
Page 183 of 281
Copyright © 2010 Traction Software, Inc.
Page 184 of 281
Copyright © 2010 Traction Software, Inc.
Note that Visitor is also listed as a special user. To define permissions for Visitor, select the Visitor radio button and click OK.
Page 185 of 281
Copyright © 2010 Traction Software, Inc.
Choosing Groups Doc33: March 22, 2008 3:48 PM, Posted by Documentation Importer
Choosing groups works the same way as Choosing Users. Click the Add Group button.
This pops the New Group ACL Entry dialog.
Page 186 of 281
Copyright © 2010 Traction Software, Inc.
You can choose Everyone or a known group from the pull-down, or lookup a group. If you try a lookup without specifying a search, Traction will issue the same warning (references to account and users in this warning actually refer to group names and groups). Page 187 of 281
Copyright © 2010 Traction Software, Inc.
This will return the list of groups. Traction groups are listed before groups from external directories.
After you press OK to the dialogs, the group is listed. Note: After you apply changes, groups are listed in blue and users in black.
Page 188 of 281
Copyright © 2010 Traction Software, Inc.
Setting Permissions Doc262: March 22, 2008 4:19 PM, Posted by Documentation Importer
You can set permissions for any user or group by selecting the user and clicking the checkbox in the Allow column next to the permission you wish to grant, or in the deny column for permissions you wish to deny.
Important! This Access Control List does not go into effect until you press the Apply button. You can edit as many settings as you like before pressing Apply. Page 189 of 281
Copyright © 2010 Traction Software, Inc.
Setting Administer Server Permissions During initial setup, you should define who you want to be allowed to administer your server. Go ahead and click the Administer Server checkbox underneath your account or group and any others you find appropriate. We highly recommend when getting started that you give yourself all permissions. To do this, add a user entry for yourself, then click the word Allow. When you click Allow (or deny), all the checkboxes in the Page 190 of 281
Copyright © 2010 Traction Software, Inc.
corresponding column are toggled between being checked and unchecked.
You can now continue defining permissions as necessary to let you get started using Traction. See Using the Server ACL Editor Intro for an description of the server permissions. You can return to the ACL editor at any time as necessary.
Page 191 of 281
Copyright © 2010 Traction Software, Inc.
Applying the ACL Doc13: March 22, 2008 3:45 PM, Posted by Documentation Importer
Once you are satisfied that you are not going to lock yourself out, go ahead and apply your ACL by clicking the Apply button.
Checking Effective Permissions Doc31: March 22, 2008 3:48 PM, Posted by Documentation Importer
Access Control Lists contain rules that define permissions. You can see the result of applying all the rules that apply to a given user or group using the Effective Permissions view. You can launch the effective permissions view by clicking the Effective Permissions button on the ACL editor.
Page 192 of 281
Copyright © 2010 Traction Software, Inc.
The effective permissions for the selected user will be displayed.
Page 193 of 281
Copyright © 2010 Traction Software, Inc.
If a permission has been granted, it shows with a green checkbox. If denied, it shows with a red X. If the permission has been neither granted nor denied, the box is blank, and the permission is not granted. You can click the User or Group button to see the effective permissions for any user or group. ACL rules can apply to users in external directories who don't even have a Traction profile. You can select external users or groups from the lookup control in the Choosing Users and Choosing Groups controls. Page 194 of 281
Copyright © 2010 Traction Software, Inc.
You can also show details for Users and Groups by clicking the Show Details link at the top-right of the Effective Permissions window.
Page 195 of 281
Copyright © 2010 Traction Software, Inc.
This view lists all server and all project permissions (if any are defined) for the named user or group.
Page 196 of 281
Copyright © 2010 Traction Software, Inc.
Overview of the Project ACL Editor Doc192: March 22, 2008 4:11 PM, Posted by Documentation Importer
The Project ACL editor works the same way as the Using the Server ACL Editor Intro. Some of the sections in this chapter are shared with that section. The Project ACL Editor allows you to grant the following permissions to any user or group, whether defined in Traction or in an external directory: Permission
Description
Page 197 of 281
Copyright © 2010 Traction Software, Inc.
Access
Governs who is allowed to see the existence of this project. Required for all but Author by Email permissions. Without this permission, no articles in this project will be visible regardless of the labels appearing on the article, and the project will not appear in any list of projects.
Read
Governs who is allowed to see this project's labels and read its articles.
Read Own Articles
Allows the specified people to read articles posted by themselves. If they do not also have read permission, they will not be able to see labels from this project.
Comment
Grants permission to post comments to this project. If Author is not provided, only comments can be posted -- not new top-level articles.
Author
Grants permission to post any type of article to this project.
Author via Email
Grants permission to post to this project by email. Using this permission, users who are denied interactive post permission may be granted permission to post via email.
Edit
Controls who is allowed to edit any article posted to this project.
Edit own Articles
Allows the specified people to edit articles originally posted by themselves.
Change Labels
Controls who is allowed to modify labels from this project during change labels operations.
Create New Labels
Controls who is allowed to create new labels in this project.
Erase
Controls who is allowed to erase any article posted to this project.
Erase Own Articles
Allows the specified people to erase articles they have posted to this project.
Read Share Folder
Controls what users are allowed to read documents Page 198 of 281
Copyright © 2010 Traction Software, Inc.
stored in this project's share folder. Write Share Folder
Controls who is allowed to post new articles to the share folder. If read is not granted and post is granted, the share folder can function as a write-only drop box.
Modify Share Folder
Controls who is allowed to edit (i.e. change the content of or post a new version of) files residing in the project's share folder.
Add Attachments
Controls who is allowed to add (and remove) attachments to entries in this project.
Administer
Controls access to this project's Project Setup views.
Page 199 of 281
Copyright © 2010 Traction Software, Inc.
Page 200 of 281
Copyright © 2010 Traction Software, Inc.
Tour of the ACL Editor The first section lists the users and groups for whom permissions have been configured. One user or group at a time can be selected. The permissions for the selected user or group appear in the Permissions panel underneath. When a user or group is selected, clicking the Show Details link in the top-right will pop up a window showing the administrative details for the user. The details window for groups shows the group membership. You can remove the selected user or group by clicking the remove button. You can add a user or group by clicking the corresponding add button. The Permissions list has three columns. The first names the permission. The next two columns have checkboxes that either allow or deny the permission. Only one of these can be checked at a time. If neither is checked, the permission defaults to not granted, except during failsafe mode: if no Login permissions have been defined, Everyone is allowed to login, and if no Administer Server permissions have been defined, Everyone can administer the server. The Effective Permissions link lets you specify a user or group and show the result of applying the entire Access Control List to that user. This can be used to preview permissions for users who have not yet logged in and for whom no Traction profile yet exists. After modifying the page, the Reset and Apply buttons become activated and the Effective Permissions button becomes deactivated. Clicking Reset throws away all edits you have made and displays the active ACL. Clicking Apply activates the ACL and re-enables the Effective Permissions button.
Sample User Details Window
Page 201 of 281
Copyright © 2010 Traction Software, Inc.
\
Sample Group Details Window
Page 202 of 281
Copyright © 2010 Traction Software, Inc.
Sample Effective Permissions Window If a permission has been granted, it shows with a green checkbox. If denied, it shows with a red X. If the permission has been neither granted nor denied, the box is blank, and the permission is not granted.
Page 203 of 281
Copyright © 2010 Traction Software, Inc.
Page 204 of 281
Copyright © 2010 Traction Software, Inc.
Getting to the Project ACL Editor Doc127: March 22, 2008 4:03 PM, Posted by Documentation Importer
Getting to the Project Access Control List (ACL) Editor The Project ACL Editor can be launched from Project Setup. You can get to Project Setup by clicking the Project Setup link in the Sidebar.
You can also jump to Project Setup using the pull-down jump menu in all Setup pages.
Once you're in Project Setup, click on the Permissions tab:
The ACL editor appears on the Permissions tab.
Page 205 of 281
Copyright © 2010 Traction Software, Inc.
You can also open the ACL editor in a pop-up window. To do this, click the Access Control List link at the top of any setup view:
Page 206 of 281
Copyright © 2010 Traction Software, Inc.
This opens the Access Control List editor window. You can switch between projects using the project selector at the top-right. You can also switch to the server access control list by clicking the Server link to the left of the project selector.
Page 207 of 281
Copyright © 2010 Traction Software, Inc.
Page 208 of 281
Copyright © 2010 Traction Software, Inc.
Configuring SMTP Doc45: March 22, 2008 3:51 PM, Posted by Documentation Importer
On the Server Setup | Email tab you can specify the address of an SMTP server.
Many more options are available in the Advanced Settings window, which you can access by clicking the Advanced Settings button.
This displays the Server Email Settings window. This window is divided into three sections: SMTP Connection Settings, Default Project Mailbox Settings., and Advanced Connection Settings.
Page 209 of 281
Copyright © 2010 Traction Software, Inc.
Page 210 of 281
Copyright © 2010 Traction Software, Inc.
SMTP Server IP Address Enter the IP address of your SMTP server here.
Authentication This governs how Traction authenticates to your SMTP server.
Use SMTP Authentication If your server supports authentication, we suggest you change this setting from no to yes.
This will open up a username and password control:
Enter the username and password of a user who is allowed to send mail using your SMTP server. Important! Note: The password will be stored encrypted in Traction. When testing SMTP, the password will be disclosed to server administrators. Users who do not have Administer Server permissions will not see the password.
Use POP Pre-Authentication While relatively rare, some mail providers require that you read email from their POP server before you Page 211 of 281
Copyright © 2010 Traction Software, Inc.
can send email using their SMTP server.
If your provider requires this type of authentication, change this setting to yes.
Enter the POP server's IP address, and the appropriate email account's username and password. Note: No mail will be downloaded or deleted from the specified account.
Encryption Traction supports both STARTTLS and SMTPS protocols.
Most administrators prefer STARTTLS, wherein a secure connection is negotiated after making an unencrypted connection if both the client and server support the protocol. Traction also supports SMTPS, which opens an SSL connection to SMTP server running on a specific port. Page 212 of 281
Copyright © 2010 Traction Software, Inc.
Important! If your mail server's certificate is not signed by a top-level certificate authority, you must configure Traction to trust your mail server. You do this using the Using the Trust Manager, which you can launch using the link in the tip text.
The best time to launch the Trust Manager is after you have tried to test your connection and gotten the error: javax.mail.MessagingException: Can't send command to SMTP host; nested exception is: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate found. The server's certificate will then be listed in the list of untrusted certificates and can be added to the list of trusted certificates with one click. This is covered in the example below.
SMTP Connection Settings SMTP Port This control lets you identify what port your SMTP server runs on.
The two most popular ports for SMTP are 25 and 587. Many systems enforce a 20-second wail period before sending mail on port 25. If you are using SMTPS you will need to enter the port your SMTPS server runs on, normally 465.
Timeouts The final SMTP options you may need to modify are in the Advanced Connection Settings section.
Page 213 of 281
Copyright © 2010 Traction Software, Inc.
Connection Timeout The Connection Timeout governs how long Traction will wait for an SMTP server to answer a connection request.. If your server has a very long timeout specified (sometimes done to prevent abuse) you may need to increase this number.
Conversation Timeout This setting controls how long Traction will wait for a non-responsive mail server before terminating the connection and abandoning the attempt to send mail.
Saving and Testing the Configuration When you believe the settings have been entered correctly, click the Apply button at the bottom of the page.
After you apply your changes, the Test SMTP button at the top of the page becomes enabled.
A window pops up showing the test results.
Page 214 of 281
Copyright © 2010 Traction Software, Inc.
Page 215 of 281
Copyright © 2010 Traction Software, Inc.
If you see the error listed, you need to add your mail server's certificate to the list of trusted certificates. To do this, launch the trust manager by clicking the link next to the Encryption Type selector.
When the Trust Manager pops up, navigate to the list of Untrusted Certificates.
Select each certificate by clicking its name in the top panel, then click the button "Add to Trusted Certificates".
Page 216 of 281
Copyright © 2010 Traction Software, Inc.
Page 217 of 281
Copyright © 2010 Traction Software, Inc.
Each certificate you add will disappear from this page. You can now switch to the page that lists the Trusted Certificates:
This page lets you verify and edit the list of trusted certificates. You can also upload a certificate to this page directly using the Browse button.
Page 218 of 281
Copyright © 2010 Traction Software, Inc.
Page 219 of 281
Copyright © 2010 Traction Software, Inc.
You can now close the window and repeat your mail test.
After you repeat the test, you should see the message, "SMTP tests succeeded. Mail settings appear to be configured properly."
Page 220 of 281
Copyright © 2010 Traction Software, Inc.
Page 221 of 281
Copyright © 2010 Traction Software, Inc.
Configuring Projects to Read Mail Doc44: March 22, 2008 3:51 PM, Posted by Documentation Importer
Setting Project Defaults at the Server Level Each Traction project can be assigned a POP3 or IMAP4 mailbox, which it can poll on a specified interval. Mail messages and their attachments can be posted to that Project provided that the permissions settings of the project allow the sender to post via email.
Setting Mail Server Defaults In order to simplify configuring many mailboxes on the same mail server, you can specify default settings for a mail server in Server Setup. Then, for each Project, you need only enter the username and password for the Project's mailbox. You do not need to configure defaults; it is just a convenience. Default project mailbox settings are specified on the Server Email Settings dialog, which you can launch from Server Setup | email by clicking the Advanced Settings button.
Alternatively, you can click the Server Settings button in any Project Mailbox Settings window.
This displays the Server Email Settings window. This window is divided into three sections: SMTP Connection Settings, Default Project Mailbox Settings., and Advanced Connection Settings.
Page 222 of 281
Copyright © 2010 Traction Software, Inc.
Page 223 of 281
Copyright © 2010 Traction Software, Inc.
Server Information Many of the values below have defaults listed. To apply a default, click the "use default" checkbox. The value will be reset to the default when you click the Apply button to apply your changes.
Protocol and Encryption Select the protocol you would like to use with your mail server. You can choose POP or IMAP. Depending on your selection, the options underneath will change.
With POP, you can choose SSL. POP3 over SSL is usually referred to as POP3S.
With IMAP, you can choose STARTTLS or SSL. IMAP over SSL is referred to as IMAPS. Most administrators prefer STARTTLS to IMAPS, which is considered to be deprecated on most systems.
Page 224 of 281
Copyright © 2010 Traction Software, Inc.
Important! If your mail server's certificate is not signed by a top-level certificate authority, you must configure Traction to trust your mail server. You do this using the Using the Trust Manager, which you can launch using the link in the tip text.
The best time to use the Trust Manager is after testing your mailbox and getting the error: javax.mail.MessagingException: * BYE JavaMail Exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate found; nested exception is: com.sun.mail.iap.ProtocolException: * BYE JavaMail Exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate found. An example of doing this is provided below.
Port Choose the port that your mail server uses for the protocol you chose. The following table lists the default ports for the various protocols: Protocol
Default Port
IMAP (with or without STARTTLS)
143
IMAPS
993
POP3
110
POP3S
995
Other Information Polling Frequency This control lets you specify how frequently projects should check for new mail.
Project Administrator's Email Address Page 225 of 281
Copyright © 2010 Traction Software, Inc.
If mail to a given project can not be posted, due to permissions, Traction will send an explanation to the sender. List here the address you would like those messages to be sent from.
Note: by default, bounce messages will not be sent to people who do not have a Traction account. If you want bounce messages to be sent to these people, set emailreceipttovisitor=true in Traction.properties while the server is shut down. By default, bounce messages will be sent to registered users if their posts are rejected. To turn these bounce messages off, you can set emailreceipttouser=false. There is currently no web interface to control these settings.
Mail Filters You can control what mail filters are enabled. Mail filters are plug-ins that can evaluate, reject, or transform incoming email messages before they are posted. Normally the default mail filters are enabled.
If you un-check the Use Default Value selection, the interface expands to show the list of mail filters installed in the server.
The filters listed in the Selected column are evaluated in the order in which they appear in this list. You can change the order by selecting a filter and clicking the up and down arrows. If you would like to disable a filter, you can select it an click Remove. To enable a disabled filter, click Add. Page 226 of 281
Copyright © 2010 Traction Software, Inc.
How HTTPS Works Doc131: March 22, 2008 4:04 PM, Posted by Documentation Importer
HTTPS uses a public key encryption system. Each server has a private key, which is used to encrypt communications with the server. Each server also has a certificate, which it presents to the browser. The certificate can be used to verify the identity of the server. It's job is to let the browser decided whether to trust the server, generally by confirming that the server is the intended server and not another server intercepting the communications. If a browser doesn't trust a server's certificate, it complains to the user. To prevent users from having to manually acknowledge every certificate, there is an industry that institutionalizes the notion of trust. Certificates can be signed by trusted organizations called Certificate Authorities (CA's) like Verisign. CA's are supposed to do background checks to verify that people requesting certificates are who they say they are. You trust Verisign, therefore you trust who Verisign trusts. Browser manufacturers like Microsoft, Mozilla, Apple, etc. trust Verisign and a handful of other CA's, and so configure their browsers to automatically trust (i.e. not complain when presented with) certificates signed by these CA's. If your certificate is signed by one of these CA's, the browser will accept it without issuing any warning the user. There are many other CA's besides the top-level CA's: the U.S. Government, low-cost providers like InstantSSL, and perhaps even your IT department. In order for HTTPS connections to "just work" and not prompt the user with a warning about a certificate, the browser must trust the certificate. But what if the certificate was not signed directly by one of the top CA's? Browsers will also trust the certificate if: • The certificate has been directly imported into the browser by the user. • The certificate has been signed by another trusted CA. As we said earlier, each browser starts with a short list of trusted CA's. There are two ways for additional CA's to become trusted: • The CA's own certificate has been imported into the browser by the user. • The CA's certificate has a trust chain showing that one of the top-level CA's trusts it. The latter is the way most low-cost CA's work; they have their own certificate signed by a higher-level CA, which has its certificate signed by an even higher-level CA, and so on up the chain until a top-level CA is reached. When a server has a certificate that has been signed by a CA with a trust chain that links it to a top CA, it can prevent the browser from complaining to the user by presenting all the signed certificates for each of the links in the chain all the way up to the top. If the browser sees that your server is trusted by someone Page 227 of 281
Copyright © 2010 Traction Software, Inc.
it trusts, it will trust your certificate too.
What you need to do to set up HTTPS Create or Import a Private Key This covers the encryption part. If you already have a key, you can use it. If not, Traction will generate one for you.
Get Your Certificate Signed This is optional; if you don't mind your users getting warned about their browsers not knowing who the server is, you can skip this step. Otherwise, you can generate a Certificate Signing Request (CSR) and pay a CA to sign your certificate. They will then send you back a signed copy of your certificate, as well as their own certificate, and all the certificates up the chain to a Trusted CA. You will need to import each of these certificates into your Traction server, which will then present the chain to the browser when a connection is made.
Setting up HTTPS Doc264: March 22, 2008 4:19 PM, Posted by Documentation Importer
Traction makes it easy to run with HTTPS. After familiarizing yourself with How HTTPS Works, follow these instructions to turn on TLS (the successor to SSL). First, go to Server Setup | Network, and change the pull-down menu from No Encryption to TLS Encryption.
When you do this, the message, "TLS Encryption requires a server private key. Click here to manage the private key." appears underneath:
Page 228 of 281
Copyright © 2010 Traction Software, Inc.
Click the link to open the Server Private Key of the Manage Trust Store interface.
Page 229 of 281
Copyright © 2010 Traction Software, Inc.
Page 230 of 281
Copyright © 2010 Traction Software, Inc.
If You Already Have a Private Key Most people don't but if you do, you'll know it. To import an existing private key and certificate pair (you'll have both), first make sure they are in PEM and PKCS8 format (you can use OpenSSL to convert them if necessary). You should now have a .pem file and a .p8 file.
Click the browse buttons and select each file, then click import. The window should update with the correct information, and you should be all set.
Creating a Private Key To create a new private key, click the generate button:
This will take you to the Generate Key page:
Page 231 of 281
Copyright © 2010 Traction Software, Inc.
You will need to fill in this form correctly.
Common Name This is the most important field. You must enter the permanent address of your server, normally its (internal or external) DNS address. For example, if your server's URL is http://traction.mycompany.com, you must enter traction.mycompany.com. Port designations, e.g. :80, :443, :8080 should not be included. Page 232 of 281
Copyright © 2010 Traction Software, Inc.
Note: if the address portion of the URL does not exactly match what you enter here, even though you pay for a certificate to be signed, the browser may still complain. If you do not have DNS set up or another permanent address for your server, you can still proceed with HTTPS configuration, but the browser will complain if the address in the URL doesn't match the address you enter here.
Organizational Unit Typically a division of an organization, often used for a branch of the company or a specific location.
City, State, Country Code Standard fare, see the example below.
Key Algorithm Traction supports RSA and DSA. If you have no reason to select DSA, we recommend sticking with the default RSA.
Key Size This is the number of bits in the generated key. Longer keys present a greater barrier to people trying to decrypt the data.
Page 233 of 281
Copyright © 2010 Traction Software, Inc.
Expiration Choose how long you want this key to be valid. The limit is 10 years. When you have filled in the form, click the Generate Key button, the Server Private Key page will return, this time showing the details for your private key.
Page 234 of 281
Copyright © 2010 Traction Software, Inc.
Page 235 of 281
Copyright © 2010 Traction Software, Inc.
Activate HTTPS Note: You do not have to activate HTTPS right away; you can do this later once you have a signed certificate, but you can activate it as early as now. Now that your private key is ready, if you would like to, you can activate HTTPS on the Server Setup | Network page. Switch back to that window and press Apply. At this point, your server is now in HTTPS mode. Most browsers indicate this by showing a lock icon in the status bar: . Due to the way HTTPS KEEP-ALIVE works, you may be able to continue talking to the server for a limited time without changing the URL, but the communication is now encrypted. Note that it is typical for HTTPS servers to run on port 443; your preferred configuration may call for a different port. In either case, now may be a good time to change the port number using the Port setting on the Server Setup | Network page. You may also choose to change the port at a later time. While it is not necessary to change the port number, it is not recommended to run Traction in HTTPS mode on port 80, which is usually reserved for ordinary HTTP services. Before continuing, we suggest you change the URL from http to https. If you changed your port number to 443, you will no longer need a port number on your URL; if you changed your port number to any other number, you will need to make sure that it is on the URL and that it correctly reflects Traction's current port number. Chances are, unless you imported a signed certificate, the first thing you will see when you connect to the Traction server is a warning from your browser.
Page 236 of 281
Copyright © 2010 Traction Software, Inc.
You can prevent this dialog by getting your certificate signed (next section). If you would rather not get your certificate signed, you can click View Certificate to show the certificate. In Internet Explorer, this looks like:
Page 237 of 281
Copyright © 2010 Traction Software, Inc.
If you would like to tell your browser to trust this certificate (and not warn you) you can install the certificate in the browser.
Getting your Certificate Signed To generate a Certificate Signing Request (CSR), return to the Server Private Key page in the Manage Trust Store dialog and click the Certificate Signing Request Generate button.
Page 238 of 281
Copyright © 2010 Traction Software, Inc.
This will show a CSR.
You can then copy and paste this into a CA's CSR form. For example, using InstantSSL, this looks like:
Page 239 of 281
Copyright © 2010 Traction Software, Inc.
Page 240 of 281
Copyright © 2010 Traction Software, Inc.
Note: Traction won't likely be listed as a server software selection, but what you select shouldn't make a difference. You can fill in the additional pages, usually just contact and credit card information. Often your certificate will arrive in email within 10 minutes. Often what you get back is a .zip file containing all the certificates in the certificate chain.
You should unzip this file in preparation for the next step.
Page 241 of 281
Copyright © 2010 Traction Software, Inc.
Page 242 of 281
Copyright © 2010 Traction Software, Inc.
In this case, the top-level CA is GTECyberTrustGlobalRoot, then ComodoSecurityServicesCA.
Importing the Signed Certificates The order you take the next steps in matters; first you must import the certificates that establish the trust chain to your signed certificate, then your signed certificate.
Importing the Trusted Certificates (Trust Chain) In our example, we need to build the chain from GTE down through Comodo to our certificate. To do this, we first import the GTE Trusted certificate by browsing to the file, tying an optional alias, and clicking Add.
The certificate appears in the list along with the private key.
Page 243 of 281
Copyright © 2010 Traction Software, Inc.
Page 244 of 281
Copyright © 2010 Traction Software, Inc.
We repeat the process for the subsequent certificates down the chain. If you don't get the order exactly right, don't worry; as long as all the trust chain certificates are added before your own certificate is imported, Traction should be able to determine the order of the chain. Here we have imported both trust certificates.
Page 245 of 281
Copyright © 2010 Traction Software, Inc.
Page 246 of 281
Copyright © 2010 Traction Software, Inc.
Importing the Actual Signed Certificate When importing this file, you need to use the Import Signed Certificate section's Import button. Browse to the file and click Import.
Traction should report Import successful:
Also, the entry for your private key should now look different; rather than just reporting the basic details, it should now show the entire certificate chain: Before Importing Signed Certificate
After Importing Signed Certificate
Page 247 of 281
Copyright © 2010 Traction Software, Inc.
Now when you close all your browser windows and reopen the web browser, you should not get any Page 248 of 281
Copyright © 2010 Traction Software, Inc.
warnings. If you click the lock icon to inspect the certificate, you will see the details. The status will be listed as OK. You will also be able to see the expiration date.
Page 249 of 281
Copyright © 2010 Traction Software, Inc.
In this case, the free trial certificate is valid for 30 days. Normal HTTPS setup is now complete.
How HTTPS with X.509 Client Certificates Works Doc132: March 22, 2008 4:04 PM, Posted by Documentation Importer, Edited by Christopher Nuzum
Page 250 of 281
Copyright © 2010 Traction Software, Inc.
In normal HTTPS, only the browser checks to make sure that it trusts the server, based on the server's certificate. When client certificates are required, the server also checks that it trusts the browser. The browser must present a certificate trusted by the server in order to be able to establish a connection. By default, Java trusts browser certificates with a trust chain to a top-level CA. However, most business and government organizations prefer to sign their own certificates. In order to get X.509 client certificates working, you need to: • Tell Traction what CA's to trust • Install certificates signed by trusted CA's in the browsers of all users. Note: It is possible to run Traction on multiple ports, with one port requiring a certificate (e.g. the port visible through the firewall) and other ports (e.g. inside the firewall) not requiring certificates. This requires modifying the Traction.properties file directly. If you need this configuration, first follow the procedure for configuring HTTPS with X.509 certificates, then contact
[email protected] for instructions on adding additional ports with different encryption levels. Note: Unlike the browser, which can install certificates not signed by any CA, Traction only allows you to import CA certificates, not certificates for individuals. Note: It is possible to prevent Java from trusting the top-level CA's, so that only certificates signed by explicitly imported CA's are trusted. Contact
[email protected] for instructions. In standard X.509 deployments, any trusted browser is allowed to connect to Traction; the authentication is handled independently. This works very well in conjunction with Active Directory and NTLM; as long as users have a signed, trusted certificate, they are automatically logged in.
Enabling HTTPS with Required X.509 Client Certificates Doc93: March 22, 2008 3:57 PM, Posted by Documentation Importer
Before continuing, you must have a client certificate installed in your browser. You must also import this certificate's CA into Traction. If you do not perform both of these steps, once you put Traction into TLS w/Client Certs, you will be unable to log in. Once you do this, all users who have client certificates signed by this CA will be able to connect to Traction. The instructions below explain how to: 1. Confirm you have a client certificate installed. 2. Export the certificate of the CA that signed the client certificate to your desktop. 3. Import the CA cert into Traction 4. Put Traction into HTTPS w/Client Certs mode.
Confirming you have a client certificate installed Page 251 of 281
Copyright © 2010 Traction Software, Inc.
These instructions are for Internet Explorer. Most browsers provide similar capabilities; see your browser's help for instructions. Select Internet Options from the Tools menu.
Switch to the Content tab and click the Certificates button.
Page 252 of 281
Copyright © 2010 Traction Software, Inc.
If one or more certificates is listed here, you can proceed. If not, stop! You don't have a client certificate and won't be able to complete the setup procedure.
Page 253 of 281
Copyright © 2010 Traction Software, Inc.
Export the certificate of the CA that signed the client certificate to your desktop. Important! Note: You do not want to export your own certificate; you must import the certificate of the CA that signed your certificate. Traction will allow you to import your own certificate, but it will not allow you to log in using that certificate! Double-click your selected certificate in the list above. If you have multiple certificates, select the one signed by the CA you wish Traction to trust. This will show your certificate.
Page 254 of 281
Copyright © 2010 Traction Software, Inc.
Click the Certification Path tab, and select the certificate of the signing CA. This is usually right above your certificate. This CA need not be trusted by the browser (indicated by the X), but it must be trusted by Traction to enable you to log in.
Page 255 of 281
Copyright © 2010 Traction Software, Inc.
Now, with the CA's certificate selected, click the View Certificate button.
Page 256 of 281
Copyright © 2010 Traction Software, Inc.
Click on the Details tab, and press the Copy to File button.
Page 257 of 281
Copyright © 2010 Traction Software, Inc.
Click Next once the Wizard opens.
Page 258 of 281
Copyright © 2010 Traction Software, Inc.
Choose the Base-64 .CER format.
Page 259 of 281
Copyright © 2010 Traction Software, Inc.
Choose a filename to which to save the certificate. You can delete the local file once the certificate has been imported into Traction.
Page 260 of 281
Copyright © 2010 Traction Software, Inc.
After you have saved the file, you can close the Wizard and other Internet Options windows. In Server Setup | Network, change the Security Level to HTTPS with Client Certs, but do not yet press Apply.
Page 261 of 281
Copyright © 2010 Traction Software, Inc.
A second link will appear underneath, reading: "TLS with Client Certificates requires that client certificates be trusted. Click here to manage trusted certificates."
Click where it says, "Click here to manage trusted certificates." This will open the Manage Trust Store's Trusted Server Certificates interface. In addition to trusting client certificates, this interface is also used to trust secure mail servers and LDAP servers. For more information, see Using the Trust Manager.
Page 262 of 281
Copyright © 2010 Traction Software, Inc.
Page 263 of 281
Copyright © 2010 Traction Software, Inc.
Next, in the Add Trusted Certificate section, browse to the file in which you saved the CA's certificate. You can type an Alias if you like. The alias is only used when interacting with the keystore using other Java tools like keytool.
Click the Add button to upload the certificate. The certificate's details will be displayed in the Selected Entry section.
Page 264 of 281
Copyright © 2010 Traction Software, Inc.
Page 265 of 281
Copyright © 2010 Traction Software, Inc.
Now that you have imported the CA's certificate, you will be able to login once you switch to TLS w/Client Certs, so you can press Apply on the Server Setup | Network page.
Now when you try to connect to your server, your browser will ask you to select which certificate you would like to present. Any certificate signed by a CA trusted by Traction can be used to establish the connection.
Page 266 of 281
Copyright © 2010 Traction Software, Inc.
Page 267 of 281
Copyright © 2010 Traction Software, Inc.
HTTPS with Client Certificate setup is now complete. You can repeat this process to import as many CA certificates as you like.
Enabling LDAP Authentication with X.509 Client Certificates Doc94: March 22, 2008 3:57 PM, Posted by Documentation Importer
If your users have X.509 certificates installed in their browsers and you are using the LDAP user directory and your LDAP server contains certificates for your users, you can have the users authenticated to Traction based on their certificate with no login required. To set this up, you must first Enabling HTTPS with Required X.509 Client Certificates. Once you do this, additional options appear on the User Directory configuration page that allow you to configure LDAP authentication.
Limitations If you run in this mode, only users with a valid certificate matching the one stored in LDAP will be able to log in. You can not create Traction-only users (users without an LDAP profile). Also, using this configuration you can not log in as Owner A special Traction account that can be enabled with a special license that allows you to get Server Administrator access to your server. This can be used if you have locked yourself out of the server due to a configuration error or forgotten password. without switching the user directory or disabling X.509 based authentication, which may require shutting down the server and editing a configuration file.
Procedure After you have configured TLS with X.509 Certificates, select the login method X.509 Client Certificates from the Login Method listed under Advanced Settings.
Note: If you are not already connected via TLS with Client Certs, you will no be allowed to select this option and will see the following error:
Page 268 of 281
Copyright © 2010 Traction Software, Inc.
Advanced Configuration When Traction is presented with a user's X.509 Client Certificate, it attempts to find a matching certificate in LDAP. To do this, it uses the search expression configured in the LDAP Searches section, where the {}'s are substituted with values from the certificate. If several results are returned, it attempts to compare the presented certificate with a certificate in each of those LDAP entries. When a match is found, the user is authenticated and associated with that account.
X.509 Client Certificate Search Expression You can control the search expression that is used to look up the users in the LDAP directory with certificates that match the one presented by the browser. This allows you to constrain the number of certificates that must be compared for equality.
Client Certificate Attribute The above search will result in a list of matching LDAP records. This option lets you determine which attribute contains the client certificate to be used for comparison.
Page 269 of 281
Copyright © 2010 Traction Software, Inc.
Troubleshooting In the event of a name collision, revoked certificate, or a mismatch between the presented certificate and the one stored in LDAP, the user attempting to connect will see the following message:
For more details, a Traction administrator can examine the Traction log file. For information on examining log files, see the section Troubleshooting Using the Log File Viewer.
In the above message, we see that there are different users with the same CN in LDAP. Because Traction defaults to using the CN for the Traction account name, there is an ambiguity that must be resolved. The first user that logs in will have the account created for them. When a second user with the same CN attempts to log in, they will get this error. To allow an account to be created for the second user, Personal Information. After the second user has logged in, rename their account. Note that neither user can use the conflicting name.
Using the Trust Manager Doc193: March 22, 2008 4:11 PM, Posted by Documentation Importer, Edited by Christopher Nuzum
The Trust Manager is the interface that lets you manage private keys and X.509 certificates in Traction. Traction uses a private key for How HTTPS Works encryption. X.509 certificates are used for: • •
Trusting other servers, e.g. Configuring Projects to Read Mail and Configuring SMTP and LDAP servers. Trusting Certification Authorities for How HTTPS with X.509 Client Certificates Works.
Links to the Trust Manager appear where they are relevant in Traction. For example, in Server Setup | Page 270 of 281
Copyright © 2010 Traction Software, Inc.
Network, when TLS encryption is enabled:
In the User Directory editor:
and in the mail server configuration interfaces.
and in failed mail tests.
Page 271 of 281
Copyright © 2010 Traction Software, Inc.
All of these links launch the Manage Trust Store window. This window is the interface to the Trust Manager.
Page 272 of 281
Copyright © 2010 Traction Software, Inc.
Page 273 of 281
Copyright © 2010 Traction Software, Inc.
Instructions for managing private keys are provided in the Setting up HTTPS section; instructions for trusting Certification Authorities is provided in the Enabling HTTPS with Required X.509 Client Certificates section. Instructions for using the Trust Manager with other servers, e.g. email servers, are provided here.
Do You Already Know the Certificate You Want to Trust? If you're a professional system administrator, you may have copies of the certificates for your mail and LDAP servers handy. If so, the Trusted Server Certificates section of the Trust Manager lets you quickly import and manage the certificates.
Page 274 of 281
Copyright © 2010 Traction Software, Inc.
Page 275 of 281
Copyright © 2010 Traction Software, Inc.
Importing Certificates To import a certificate, click the Browse button to locate the .PEM or .CER file on your system, type an alias for it, and press the Add button.
Removing Certificates To remove a certificate, select it in the list of certificates, and press the remove button.
Letting Traction Capture the Certificate for Your Review When you try an operation in Traction that requires that you trust a certificate that you have not yet added to your list of trusted certificates, Traction will report an error message and present you with a link to the Trust Manager's Untrusted Certificates page. For example, you may be testing a mail server configured with STARTTLS. You have entered all the mail settings correctly, but the Test SMTP operation returns an error and a link to the trust manager:
Page 276 of 281
Copyright © 2010 Traction Software, Inc.
If you get this type of error, click the link to launch the Trust Manager.
Page 277 of 281
Copyright © 2010 Traction Software, Inc.
Page 278 of 281
Copyright © 2010 Traction Software, Inc.
The certificate presented by the server you just contacted will be listed (along with any other certificates from other attempts). From here, you can select the certificate for the server(s) that you wish to trust and click the Add to Trusted Certificates button. When you do this, the certificate will disappear from this list and be added to the list of certificates in the Trusted Certificates section. If you switch to the Trusted Certificates section:
You will see the certificate you just added listed:
Page 279 of 281
Copyright © 2010 Traction Software, Inc.
Page 280 of 281
Copyright © 2010 Traction Software, Inc.
If you repeat the test (whether contacting a mail or LDAP server), it should now succeed without error.
Page 281 of 281
