Please see text links at bottom of page for navigation

iTools 5.0 Technical Frequently Asked Questions (FAQ)

iTools version 5.0 for Mac OS X Server

Updated: October 10, 2000

This collection of Frequently Asked Questions (FAQ) provides brief answers to many common questions about the setup, installation, and configuration of Tenon's iTools software. Please check here for answers before contacting Technical Support.

Return to top of page

Installation

1. Question: I re-installed iTools, and now my Apache complains about SSL-related directives in the apache.conf file. What gives?

Answer: The iTools installers prior to iTools 5.0010 installs the default "apachectl" program in place. Users iTools 5.0010 and later will not experience this difficulty. The default apachectl file located in "/usr/sbin" and does not contain the necessary definition to enable SSL. This situation can be rectified two ways. One way is to simply re-install the SSL package. The recommended way is to edit the apachectl file and change this line:

HTTPD="/usr/sbin/apache"

TO:

HTTPD="/usr/sbin/apache -DSSL"

This enables the SSL module and your SSL should begin to work once Apache is restarted.

2. Question: How do I uninstall iTools?

Answer: iTools (or any other OS X package) can be easily uninstalled restoring Apple's default configuration. The uninstaller is located in:

/Local/Library/Receipts/iTools.pkg

Return to topic list

Squid and caching

3. Question: I reguarly update documents on the web server, but the updates never seem to appear. What's wrong?

Answer: It is important to understand how caching works on a web server, and in a web browser. Here is a hypothetical scenario that will explain the issue:

iTools is operating under normal conditions and a commonly-accessed page is located in the Squid cache. A browser requests this page and it is transmitted by Squid without checking to see if the page has updated. This is where iTools' speed comes from. Now, if a browser "Reload" request is given by the browser to Squid, Squid will check to see if the page has updated and it will serve the latest copy. If a "Super-reload" request is given to Squid it will serve the page from disk no matter what.

Squid keeps commonly-accessed pages in its cache for three days. Once this time has expired, Squid automatically dumps the contents of its cache and commonly-accessed pages are stored in cache as they are accessed.

Netscape has an option entitled "Page in cache is compared to page on Network". The options for this feature are: "Once per seession", "Every time", and "Never". If Netscape is set to "Never", it will never ask Squid if the page is updated! If the option is set to "Once per session", Netscape will ask once if the page has been updated, and if the option is set to "Every time", Netscape will always ask Squid if it has the latest document. Tenon recommends that you set your Netscape settings to verify documents "Every time". This gives you the maximum "Reload" functionality. To force Netscape to do a "Super-reload", simply hold down the "option" key while clicking "Reload" on Macintosh systems, and hold down the shift key while clicking "Reload" on all other platforms.

Unfortunately, Internet Explorer does not have the cache options that Netscape does. The best IE can do is a "normal" reload which is initiated by holding down the shift key and clicking the reload button. Numerous users have encountered problems with IE because it rarely (sometimes never) checks to see if the page on the network has changed and will only serve up documents out of its cache. Until Internet Explorer handles caching properly, we strongly recommend against using IE for web-page verification.

4. Question: I am receiving Squid errors indicating "aclParseAclLine: IGNORING invalid ACL: acl thishost src". How do I correct this problem?

Answer: Look in your "/usr/local/squid/etc/squid.conf" file, and search for the line that looks like "acl thishost src". Change this line to read "acl thishost src 10.0.0.1" where "10.0.0.1" should be replaced the IP address of your OS X Server machine.

5. Question: When I view the running processes on my iTools system, I see these "(dnsserver)" processes. What are they for? Are they related to BIND?

Answer: If you type "ps alx" on the command line, you will find that these processes are children of squid. They are used to cache DNS lookups to aid in Squid's high-speed caching algorithm.

Return to topic list

Mac OS X Server

6. Question: How does iTools make use of the settings entered into the Mac OS X Server network control panel?

Answer: When iTools is installed, it uses the "hostname" entered into the Network control panel on OS X Server and the domain name entered in the "Search Domains" section of the Network control panel to set up a number of configuration files and settings on the machine.

It will use those settings to configure a virtual host container in the apache.conf file, and it will create default DNS files based on those settings as well.

Return to topic list

Advanced Setup

7. Question: I want to use my iTools machine as a proxy server, and I have enabled the proxy cache in the "Proxy" section of the admin server, but nothing appears to work. What's wrong?

Answer: In iTools, the Proxy cache comes shipped disabled due to the overhead in the Proxy module. In order to enable the Apache Proxy, uncomment lines 859-887 in your /Local/Library/WebServer/Configuration/apache.conf file. Make sure that there is only one "ProxyRequests On" directive in your apache.conf file. Once this is done, make sure that the /Local/Library/WebServer/ProxyCache directory is owned by user "www" so that Apache can write to it. Once this is done, restart Apache and the admin server, and your ProxyCache should work.

8. Question: I would like to enable the Squid Proxy server because of its increased performance and functionality over the Apache Proxy Server. How do I set this up with iTools?

Answer: The answer is quite simple. First follow the instructions in the following WebTen paper: http://www.tenon.com/support/webten/papers/webten-squidproxy.shtml. Next, find the line in the squid.conf file that says "tcp_outgoing_address". You will find that the default value for this directive in iTools is "127.0.0.1". Change this to "0.0.0.0", and your Squid Proxy will now work.

9. Question: I am using characters with umlauts and accents in my HTML documents. The documents look fine on the screen, but the characters show up differently when viewed with a web browser. How do I fix this?

Answer: There are a number of ways to resolve this issue. The solution involves sending a modified HTTP header to instruct the web browser to display the document with a different character set.

ISO 8859-1 is just one part of the ISO-8859 standard, which specifies several character sets:

ISO-8859-1 Europe, Latin America, Caribbean, Canada, Africa
ISO-8859-2 Eastern Europe
ISO-8859-3 SE Europe/miscellaneous (Esperanto, Maltese, etc.)
ISO-8859-4 Scandinavia/Baltic (mostly covered by 8859-1 also)
ISO-8859-5 Cyrillic
ISO-8859-6 Arabic
ISO-8859-7 Greek
ISO-8859-8 Hebrew
ISO-8859-9 Latin5, same as 8859-1 except for Turkish instead of Icelandic
ISO-8859-10 Latin6, for Lappish/Nordic/Eskimo languages

Based on the character set that you want to choose, you need to add a line to your /Local/Library/WebServer/Configuration/apache.conf file. If you were having a problem with umlauts not showing up properly, then this would mean that you would need to choose the ISO-8859-3 character set. This could be done with the following line:

AddType "text/html ; charset=ISO-8859-3" .html

This will cause the HTTP header to look like this:

Content-type: text/html ; charset=ISO-8859-3

Instead of the default:

Content-type: text/html

You can also display character set specifications in HTML by using the <META> tag in the HTML code. A meta tag that will cause the character set to be selected in the browser looks like this:

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">

10. Question: I get an "Internal Server Error" when I try to view "Server Status" and "Server Info" in the "Server Controls" section of the admin server. Why is this?

Answer: Along with the "Internal Server Error" error message, you will usually get an error message in the Apache Error Log to the effect of "AuthType not set!". This is because the directive in the "/Local/Library/WebServer/tenon/apache/conf/iTools.conf" file that sets "AuthType" only applies to directories under "/Local/Library/WebServer".

The easiest solution to this problem is to make sure that your content lies underneath the "/Local/Library/WebServer" directory.

An alternate solution is to duplicate the "<Directory /Local/Library/WebServer>" container (it will end with </Directory>) and change "/Local/Library/WebServer" to reflect the new location of your content.

11a. Question: What is a TCP/IP wrapper?

Answer: A TCP/IP wrapper is a daemon which runs in place of other services on your machine, catches incoming requests for services and hands them off to the appropriate daemon (or denies them) based on teh IP address of the requesting host.

The TCP/IP wrapper works in conjunction with inetd and so only handles those services controlled by inetd (i.e. it doesn't work to control access to iTools but iTools provides it's own services in this respect).

b. Question: Why would I want to run a TCP/IP wrapper?

Answer: Certain services on your machine are very useful but also very powerful and prone to being misused. Protecting these services so that only clients at known addresses can access them is very useful.

c. Question: Where can I get a TCP/IP wrapper?

Answer: The standard location for this used to be:

ftp://ftp.cert.org//pub/tools/

but Cert seems to have recently stopped maintaining this directory. We were able to locate the current version at:

ftp://ftp.porcupine.org//pub/security/

and this seems to now be the canonical repository for this and other tools written by Wietse Venema.

d. Question: What system type do I use to build this?

Answer: We were able to build this with no errors by using the "Freebsd" system type.

e. Question: Are there any specific issues related to Mac OS X Server?

Answer: Yes, it was necessary to specify absolute paths in the modified inetd.conf file to get this to work.

Old inetd.conf line:

finger stream tcp     nowait nobody /usr/libexec/fingerd    fingerd -s

What we would have expected:

finger stream tcp     nowait nobody /usr/etc/tcpd    fingerd -s

What we had to use:

finger stream tcp     nowait nobody /usr/etc/tcpd    /usr/libexec/fingerd -s

See also: http://www.macsecurity.org/resources/xinetd/
http://www.stepwise.com/Articles/Workbench/Using_tcpwrappers.html

Return to topic list

Backup/restore of configuration

12. Question: How do I back up my license file?

Answer: The iTools license file is located in "/Local/Library/WebServer/tenon/etc". The license file is called license.info. This file can be copied or backed up to prevent having to re-enter the license information in case it becomes damaged.

13. Question: I want to upgrade to OS X Server 1.2. How will this affect my iTools installation?

Answer: These are the steps you must take to ensure a seamless transition to OSXS 1.2:

Backup:

  /Local/Library/WebServer/tenon/etc/users.db
  /Local/Library/WebServer/tenon/etc/groups.db
  /Local/Library/WebServer/tenon/etc/license.info
  /etc/sendmail.cw and sendmail.cf
  /etc/ftpaccess
  /Local/Library/WebServer/tenon/libexec/iTools.sh
  /Local/Library/WebServer/tenon/apache/conf/iTools.conf
  /Local/Library/WebServer/Configuration/apache.conf

Install the OSXS 1.2 Update.

Remove all of the lines from the file:

 /Local/Library/WebServer/tenon/logs/iTools.Updates

Re-install the main iTools package.
Replace the backup files from step 1.
Restart the machine (optional but recommended).
Enjoy!

Return to topic list

Mail

14. Question: WEBmail tells me that my e-mail address is "hostname.domainname", but I want to receive mail for "user@domainname". How do I do this?

Answer: iTools has a feature that automatically adds entries to the "/etc/sendmail.cw" file whenever a virtual host is added or deleted. The "sendmail.cw" file is a list of hosts for which sendmail will receive mail. If a server's fully-qualified hostname was "www.tenon.com", the entries that the admin server would place in the sendmail.cw file would be as follows:

www
www.tenon.com
#tenon.com

This means that if you could send mail to "user@www" (if you were on the same net as the tenon.com domain) or "user@www.tenon.com". The domain is commented out so that it does not disrupt mail delivery for your domain in case you have a separate mail server for your domain. If you want your iTools machine to handle mail for your domain, simply remove the "#". Then, mail will be received for "user@tenon.com" (provided that the DNS MX records were set up properly).

If you have another server who receives mail for the domain (in this case "tenon.com"), then you may want to delete the "tenon.com" entry from the sendmail.cw file. Upon "HUP" of sendmail, the changes will take effect.

15. Question: I try to send mail through the iTools SMTP server (sendmail), and I get an error stating "Relaying denied". What gives?

Answer: As of sendmail 8.9.3, the default operation for sendmail is not to relay messages. We have added in recent version of iTools a file in the /etc/mail directory called relay-domains. In this file, list all hosts for which you want to relay mail for. Ideally this would include one or two domains clients log in from to access your mail server. The file might look like this:

tenon.com

If your relay-domains file looked like the above, it would mean that sendmail would relay mail only from tenon.com. The relay-domains file entries can be as specific or as general as you wish. Remember to HUP sendmail for the changes to take effect.

For more information, please see the following documents. For the relaying entry in the sendmail FAQ, please see:

http://www.sendmail.org/faq/section3.html#3.27

For further information on sendmail relaying, please see this document:

http://www.sendmail.org/tips/relaying.html

Return to topic list

WebCatalog

16. Question: After I restart my machine, everything works except that WebCatalog doesn't start. Why is this?

Answer: In the default iTools installation with WebCatalog, WebCatalog is started as a process of mod_fastcgi. This behavior is controlled by the FastCGIServer directive in the "/Local/Library/WebServer/tenon/apache/conf/iTools.conf" file. You should see an entry that looks like this:

<IfModule mod_fastcgi.c>
FastCGIServer WebCatalog/WebCatalog
</IfModule>

If this is present, then WebCatalog should start with Apache and stop with Apache. Possibly some post-install misconfiguration caused these directives to be removed or commented out.

Return to topic list

iTools Administration Server

17. Question: I accidently added a VirtualHost that resolves to another machine's IP address. What do I do to fix the confilict?

Answer: Simply delete the offending VirtualHost in the iTools admin server. iTools will automatically take down the offending IP address and VirtualHost. The DNS should then be fixed to point to the correct IP and the VirtualHost can be added again. DO NOT just delete the record from the apache.conf file. If you do, the IP address will continue to cause a conflict.

18. Question: Why do I have to log in twice to the iTools Administration Server?

Answer: The reason why you must log in twice to the admin server is because it is protected two ways. The URL "http://yourhostname/itools_admin" is password protected because this URL starts the admin server. You would not want others to be able to start the admin server (which consumes system resources) to be activated when you did not want to use it. The Admin Server itself requires authentication. This is necessary so that the Admin Server is not accessible to the world when it is running -- you wouldn't want other changing sensitive server settings without your knowledge.

The first challenge is from Apache, and the second challenge is from the Admin Server itself. Web browsers will remember the username/password combination for that session, and you will not be asked to authenticate yourself until you quit and restart the browser. If the admin server is already running, you can access it at the URL "http://yourhostname:84/". In this case, you will only be required to authenticate yourself once since you are bypassing Apache altogether.

19. Question: Why do I get "DNS Mismatch" for some of my virtual hosts in the Admin Server?

Answer: The Admin Server prints the error "DNS Mismatch" for virtual hosts when a forward and reverse lookup on the hostname listed in the virtual host container, and the two lookups do not match. The solution is to fix your DNS so that the forward and reverse lookups will match.

Return to topic list

DNS

20. Question: I seem to be having trouble performing zone transfers to a secondary DNS server when iTools is running as my primary DNS server. What is wrong?

Answer: iTools does not ship with any restrictions on who can do zone transfers. In a default iTools configuration, anybody can request a zone transfer from your machine.

It is a common problem that a secondary DNS server is not able to slurp records from the primary DNS server because it does not believe that the primary DNS server is authoritative for that domain. In this case, make sure that your Internet Domain Name Registry service is pointing to both your primary and the secondary DNS server in its records for your domain. This will allow your servers to become authoritative, and the secondary DNS will magically start working.

21. Question: Can I use an MX record to redirect mail destined for my domain to a POP account?

Answer: No. A mail exchange record is generally used to direct mail addressed to a domain name (user@mydomain.com) to the hostname or IP address of a mail server that is handling mail delivery for that domain.

Redirecting mail is typically done by mail delivery and mail routing software such as sendmail. The easiest way to forward mail with sendmail is the use of a ".forward" file. Please see the sendmail documentation for more information.

22. Question: I want to set up "round-robin" style load-balancing. What are the steps?

Answer: Because iTools automatically performs DNS lookups to configure your virtual hosts, some special consideration is needed to properly configure the two servers.

Make sure that both servers are pointed to your own DNS server for lookups.
Configure only the first DNS IP address entry for the host you wish to load-balance.
Configure the virtual host you wish to load balance on the first server.
Change the DNS entry to point only to your second server's IP address.
Configure the virtual host you wish to load balance on the second server.
Now, configure the DNS for the host to point to both server's IP addresses. In iTools this is done by simply adding another IP address to the list under the hostname.

These steps ensure that each virtual host will be configured correctly with the proper IP address. If you still have trouble with this process please contact Tenon Tech Support.

Return to topic list

Networking

23. Question: Can multiple IP addresses be assigned to a single ethernet interface?

Answer: Modern operating systems provide a featured called "IP Aliasing" which allows a single ethernet interface to listen on more than one IP address. This is sometimes referred to as "multihoming". The iTools Admin Server makes this complex networking configuration easy because it takes care of configuring and deleting the IP aliases from your OS X Server machine's configuration automatically when you add and remove virtual hosts using the Admin Server.

Return to topic list

FTP

24. Question: FTP users are locked into the home directories assigned to them. Is there any way to change this?

Answer: The default FTP user configuration in iTools "chroots" users to their home directories. This is done via a combination of FTP server configuration and the admin server. The admin server assigns FTP users to the group "ftpguest" which has group id (gid) 32. There is a directive in the "/etc/ftpaccess" file that initiates the "chrooting" of FTP users in group "ftpguest". If you would like your FTP users to be able to see other files on the filesystem, simply remove them from the "ftpguest" group.

Return to topic list

Miscellaneous

25. Question: I installed MySQL, but I don't know how to get it running.

(Thanks to Lon Baker from the iTools mailing list for providing the information on which this answer was based.)

Answer: A good place to start is MySQL & mSQL book by O'Reilly by Yarger, Reese, and King. Pages 41-43 describe how to start, stop, etc.

Basic command to start:

/usr/local/mysql/bin/safe_mysqld &

This gets mysql running in the background.

Set password with:

.bin/mysqladmin -u root password 'thenewpassword'

Test it with:

.bin/mysqladmin -p create DATABASENAME

This should prompt you for the password you just created. If successful, the database is created.

Then, type:

.bin/mysqladmin -p drop DATABASENAME

This should get you started with MySQL. Please check the documentation on MySQL website or the aforementioned O'Reilly books for more information.

26. Question: Now that I have a movie in '/Local/Library/QuickTimeStreeaming/Movies/', what URL do I use to view it?

Answer: You can view the movie by opening movieplayer on a client Mac or PC (movieplayer on the server will not work). Then, select 'open URL' from the 'File' menu. In the field there type:

rtsp://server.domain.com/moviename.mov

And your movie will start to stream.

27. Question: The executable "acroread" seems to be missing from my machine. I receive error message reporting its non-existence when I index my site with ht://dig.

Answer: "acroread" is the name for the executable file for Adobe Acrobat Reader on Unix systems. It does not come with iTools, ht://dig, or OS X Server. To my knowlede (and the Adobe web page), Adobe Acrobat is available for MacOS, Linux, IRIX, Windows 3.1/95/98/NT/2000, SunOS, Solaris, AIX, DEC Unix, OS/2, and HP/UX. Adobe's website does not indicate that there is a version available for Mac OS X Server or any plans for such a release. Until there is, you will not be able to use ht://dig to index PDF files on your website (unless you have another program that can take the place of Acrobat).

28. Question: iTools quits every two hours. What is wrong?

Answer: If your server is stopping every two hours, it is most likely because your license number expired. Your license number can be changed either by using the iTools app, or by running the command-line "chnglicense" program.

29. Question: How do I keep my web content on a different drive?

Answer: The easiest way to accomplish this is to place your data in a directory on the new drive, and use symbolic links to link into the "WebSites" directory (the default place for content on iTools).

An alternative (and more difficult) solution is to place all of your web users and content on the new drive. You could copy the data to the new drive, and mount it to "/Local".

30. Question: I notice with iTools I can create users with more than 8 characters in them without any problems. I go to modify/look at said user in the NetworkManager and I'm asked to constantly save changes to the user, but of course am not able to because the user is longer than NetworkManager likes. So I just close the user without any changes made and everything's good (I mean i'll change the user with iTools it necessary).

So how then is Mac OS X Server able to chirp along happily with longet than 8 character users, but _only_ those created with iTools?

Answer: Change the OS X Server Network Manager options to allow for longer usernames. Go to the Users section of the Network Manager and click on the gray face with a pencil (if you hold the mouse over this guy, it will say "Edit User Defaults"). After you click on this button, a dialog box will show up. Edit the field that says "Maximum Name Length". Chances are, yours has the value of "8". Change the value to something more reasonable like "24". This will allow for longer usernames.

Return to topic list