======================================================================= Netscape FastTrack 2.0 (Unix) ======================================================================= Thank you for being a beta tester for the Netscape FastTrack server. This message gives you instructions about how to get and install the software. We assume you are already familiar with web servers. Netscape FastTrack 2.0 is subject to the terms detailed in the license agreement file called license.txt. SOFTWARE EXPIRATION This beta software will expire in August 1996 The administration server warns about this fact and includes the exact date and time of expiration. Make sure you upgrade to a newer beta or the final product before that date. THIS IS BETA SOFTWARE As with any beta software, it might have bugs. Beta software should be considered experimental and not to be run on a production system without first verifying that all the expected features work. We encourage you to send feedback on this product. Feel free to comment on the user interface, the online help, the feature set, Java and JavaScript support, or any other area of the product. To submit bugs or other feedback, send email to: ubeta@netscape.com We'll only contact you if we need further information. ======================================================================= Installation Instructions ======================================================================= Before you install the FastTrack server, you need to make sure that DNS is running. Before you can install the server, you must have installed Netscape Navigator. You can download the latest version from: http://home.netscape.com. To install the server, Download the .tar file for your operating system into a temporary directory, and then unpack the file using the command: tar -xvf This unpacks all the files. You can run the setup application by typing ./ns-setup and follow the onscreen directions. If you're upgrading from a 1.1 server, you must install this beta version into a separate directory first, and then you can run the "upgrade" script located in the install directory. ======================================================================= Troubleshooting ======================================================================= * DNS should be enabled on your Unix machine; otherwise the administration server won't run using hostnames. The administration server is used to manage and configure your web server. If you don't have DNS, you can use IP addresses, instead of hostnames, during installation. You'll also need to use IP addresses when accessing the Server Selector pages of the administration server. * The administration server doesn't currently support SSL (encryption). ======================================================================= Upgrading NSAPI from 1.1 to 2.0 ======================================================================= For the most part, NSAPI is unchanged in the 2.0 servers. Additional functionality and abstractions were added, and many macros were converted to function calls. This means you have to recompile your existing NSAPI modules. * Threading In addition to the NT servers being multithreaded, all of the 2.0 Unix Web servers are multithreaded. There are new abstractions in base/systhr.h and base/crit.h for threads, critical sections, and condition variables. The Unix servers are still capable of running in multiple-process mode. Each process then has a pool of threads that it uses to answer requests. If your NSAPI modules are not thread-safe, you can run the server with 1 thread per process to simulate the 1.1 server architecture; however this can result in a performance loss. You can run 1 process with multiple threads to simplify programming. This lets you share context without using shared memory. However, high traffic sites that use CGI should use several processes (2-8) with fewer maximum threads per process. For example, if you normally run 1 process with 128 threads, run 4 processes with 32 maximum threads each if your site serves a very high volume. This avoids large virtual address spaces for a single process. New thread manipulation calls exist in base/systhr.h. The following functions can manipulate threads: systhread_start, systhread_current, systhread_terminate, systhread_sleep, systhread_yield, systhread_newkey, systhread_getdata, and systhread_setdata. Note that creating a new thread in an Init function results in undefined behavior under Unix. If the thread does something periodically, that action will happen in both the base server process and all of its children. The functions defined in base/sem.h remain the same and provide server-wide mutual exclusion. Under NT, these are simply critical sections that apply to all threads in the server process. Under Unix, these primitives operate on all threads in all processes of the server, so they are very heavyweight. They should only be used to protect access to process-shared resources such as shared memory and files. New calls exist in base/crit.h that provide process-local critical sections and condition variables for NT and Unix. These calls only affect threads in the current process. Critical sections are simply a lock that can be owned by only one thread at a time. They can be recursively entered. Condition variables are used in conjunction with a critical section to provide "wait" and "notify" primitives. On IRIX, Solaris 2.x, and OSF/1, the operating systems provide threading support, and multithreaded versions of libc. On those systems, you can call most libc routines safely. One notable exception is that you must use localtime_r and gmtime_r instead of localtime and gmtime respectively. Many other functions also must be called in their reentrant form. Check the man pages for details. On systems that don't have threading support, we provide the threading via user-level context switches. The server doesn't currently try to perform thread pre-emption, which means that you can still use libc calls that aren't re-entrant. Thread switching is performed when a lock is used, when the NSAPI I/O functions such as net_read are called, and when a systhread_yield() is explicitly called. This also means that if your NSAPI extension makes a system call that will block, you will block the process that your thread is running in (thus blocking all threads in that process). DNS calls such as gethostbyaddr() are one example of a call which will block the process, however the NSAPI function session_dns will not block the process. Under IRIX, you must compile with -D_SGI_MP_SOURCE. Under Solaris, you must compile with -D_REENTRANT. Under OSF/1, you must compile with -threads. * Init directives in obj.conf Init directives moved to obj.conf. You can still enter them in magnus.conf, but the administrative interface prefers them in obj.conf. * Memory arenas The default MALLOC, FREE, and STRDUP macros have been changed to use arenas of memory instead of allocating each memory request directly from the system heap. One arena is created for each request, and it is freed after the request is processed. If you need to allocate memory for a global variable, or for a variable which will persist after a request is finished, use the PERM_MALLOC, PERM_FREE, and PERM_STRDUP macros instead. The data in the Request pblock is allocated via MALLOC, not via PERM_MALLOC so when manipulating these structures be sure to use the correct macro. You can also run the server with memory pools disabled. In this case, both MALLOC and PERM_MALLOC will use the system heap for memory. To disable the memory pools, place the following line at the top of obj.conf: Init fn=pool-init disable=true Running in this mode lets you interact with libraries that expect to be able to free memory you send to them, but may result in decreased performance. * Shared memory There is a new abstraction for shared memory in base/shmem.h. The new structure is called shmem_s, and the "data" member contains a pointer to a shared memory region of the requested size. Public functions are shmem_alloc and shmem_free. This memory is created as a file. If you allocate shared memory in an Init function, and keep a pointer to it in a global or static variable, it will be accessible by all server processes. Under NT these calls affect only the server process, but the shared memory may be made visible to other processes on the system. * Network I/O calls in base/net.h There are more network calls in base/net.h: connect, writev, and ioctl. Some were removed. The calls defined in net.h were macros, but they are now functions. Assume that the calls operate very closely to the Unix socket or WinSock call that they're named after. The mysterious "slot" parameter that existed in some versions of the 1.1 NT server but not the Unix server has been eliminated. The API for net_read and net_write is the same under both Unix and NT again. * servact.h Some calls from frame/req.h were moved into frame/servact.h (which includes frame/httpact.h). Compatibility macros are provided in req.h. * Caching The 2.0 server attempts to cache requests that will create the same response when requested by multiple clients at different times. That is, if a client requests /foo/bar/baz.txt, and then another client requests /foo/bar/baz.txt, the server's response will be the same as long as /foo/bar/baz.txt doesn't change between the requests. When the server can avoid calling the NSAPI functions for a request, it can return the responses faster. There is a new variable called "directive_is_cachable" in the Request structure in 2.0. By default, this variable is set to 0 when calling your NSAPI functions. If you do not set this variable to 1 before your function returns, the server will not try to cache the request, and each subsequent request will call your function again. If you set it to 1, the server may not call your function when the next client makes the same request. You should cache requests that do not depend on some aspect of the client to determine how they are returned. If your function performs access control, logging, switches data based on user-agent, or anything similar, you should not mark your directive as cachable. If your function is doing something which does not depend on the client IP address or the headers the client sends, then you can mark your directive as cachable. * Software multihoming Netscape Navigator 2.0 and some other browsers now send a Host: header telling the server which URL host and port is being accessed. In addition to the 1.1 functionality of making your obj.conf directives conditional on the client's IP address, you can also specify that they only be executed when the URL host is a specific pattern. For example, NameTrans fn=my-nametrans from=/anysuchdir placed in the default object will call my-nametrans only when the browser thinks it is accessing www.any.com or www.auch.com. Similarly, NameTrans fn=my-nametrans from=/anysuchdir will apply my-nametrans to everyone except those who access www.any.com and www.such.com including browsers that don't send the Host: header. * New header files There are some header files in this beta that might not be included in the final release. New headers that were not in 1.1 that are mentioned in this document will stay, but others won't.