Passing environment variables from an hypertext protocol server application programming interface

[0002] The present invention relates generally to passing information between client and server programs in a Web transaction environment.

[0003] The World Wide Web of the Internet is the most successful distributed application in the history of computing. In the Web environment, client machines effect transactions to Web servers use the Hypertext Transfer Protocol (HTTP), which is a known application protocol providing users access to files (e.g., text, graphics, images, sound, video, etc.) using a standard page description language known as Hypertext Markup Language (HTML). HTML provides basic document formatting and allows the developer to specify “links” to other servers and files. In the Internet paradigm, a network path to a server is identified by a so-called Uniform Resource Locator (URL) having a special syntax for defining a network connection. Use of an HTML-compatible browser (e.g., Netscape Navigator) at a client machine involves specification of a link via the URL. In response, the client makes a request to the server identified in the link and receives in return a document formatted according to HTML.

[0004] HTTP servers available from Netscape Communications Corporation (Mountain View, Calif.) are in common use. Netscape HTTP servers provide a plug-in application programming interface (API) which allow non-Netscape programs to override or enhance the functionality of the HTTP server. In a typical Web transaction, an HTTP server follows a defined sequence of steps, called server methods, when responding to a request from an HTTP-compliant browser. These steps include authenticating user id's and passwords, mapping URL's to local filesystem path names, checking user access to translated paths, identifying additional object types on requests, performing service requests (e.g., return objects or execute CGI programs), and log server events. The plug-ins can be called to execute within a Netscape server process to override or complement these server methods.

[0005] Serving Common Gateway Interface (CGI) programs are an important part of the HTTP server function. CGI programs are typically used to return dynamic information and to respond to HTTP browser input in HTML forms. They normally run as child processes created under HTTP server processes. There has now been recognized a need to insert environment variables into CGI program processes. There are several reasons for this. Thus, for example, a plug-in might need to set authentication information in the child process so that a CGI program can access protected resources on the browser user's behalf. Or, it may be desirable to set up application preferences specified by the user, or to set path information based on the location of a desired application.

[0006] Presently, Netscape HTTP servers do not provide a mechanism for setting dynamic, non-Netscape defined (sometimes referred to herein as “non-conforming”) environment variables in CGI processes. Non-conforming environment variables can be set in the initial configuration (using the init-cgi directive), but these variables are not dynamic in that they cannot be set or modified by plug-ins. Plug-ins can partially define environment variables by inserting a variable name into a Netscape parameter block (pb) called request->headers. However, when the Netscape send-cgi service method executes the CGI's process, it “mangles” the resulting environment variable by prepending “HTTP_” in front of the initial variable name. This is useful if the plug-in developer has control over the CGI programs being executed, but plug-ins may need to provide a service that is transparent to existing CGI programs.

[0007] It would therefore be desirable to provide a mechanism to pass non-conforming environment variables from plug-ins to CGI processes and preferably without fully overriding the server send-cgi service method.

[0008] It is thus a primary object of the invention to enhance the functionality of an HTTP server application programming interface to enable passing of non-conforming environment variables from hypertext transfer protocol (HTTP) server plug-ins to Common Gateway Interface (CGI) programs.

[0009] It is a more particular object to provide a mechanism to pass non-conforming environment variables from plug-ins to CGI processes without completely overriding a send-cgi service method of the HTTP server.

[0010] It is a more general object of the invention to enhance the functionality of an HTTP server application programming interface without modifying the server method used to handle CGI service requests.

[0011] These and other objects of the invention are achieved in a method of enabling a generic plug-in of an HTTP server to pass an unmangled environment variable into a CGI process. In accordance with a preferred embodiment, the method begins by configuring the HTTP server to initially override a CGI service method. When the server processes an HTTP request, the generic plug-in, which is called prior to the CGI service method and is running in a process of the HTTP server, inserts a “name value” pair prepended with a marker in a request header parameter block of the HTTP server. Then, a CGI service override method of the invention executes the server's original (i.e. native) CGI service method, causing it to run an encapsulation program in the CGI process. This program scans the environment of the CGI process for any string prepended with a given HTTP code (e.g., the string “HTTP_”) and the marker. If it finds any such string, the program strips the given HTTP code and the marker from a remainder of the string and resets the environment variable into the CGI process in an “unmangled” form. The target CGI program is then executed in the CGI process.

[0012] The foregoing has outlined some of the more pertinent objects and features of the present invention. These objects should be construed to be merely illustrative of some of the more prominent features and applications of the invention. Many other beneficial results can be attained by applying the disclosed invention in a different manner or modifying the invention as will be described. Accordingly, other objects and a fuller understanding of the invention may be had by referring to the following Detailed Description of the Preferred Embodiment.

[0013] For a more complete understanding of the present invention and the advantages thereof, reference should be made to the following Detailed Description taken in connection with the accompanying drawings in which:

[0014] FIG. 1 illustrates the known Internet client-server paradigm;

[0015] FIG. 2 is a flowchart of the methods that are carried out by a Web server in response to receipt of a request from a client machine;

[0016] FIG. 3 is a process flow diagram showing how a server process launches a CGI child process according to a known technique; and

[0017] FIG. 4 is a modification of FIG. 3 illustrating the present invention; and

[0018] FIG. 5 is a detailed flowchart describing the process flow of the invention.

[0019] A representative system in which the present invention is implemented is illustrated in FIG. 1. A client machine 10 is connected to a Web server platform 12 via a communication channel 14. For illustrative purposes, channel 14 is the Internet, an Intranet or other known connection. In the case of the Internet, Web server platform 12 is one of a plurality of servers which are accessible by clients, one of which is illustrated by machine 10. A client machine includes a browser 16, which is a known software tool used to access the servers of the network. Representative browsers include, among others, Netscape Navigator (all versions), Microsoft Internet Explorer (all versions) or the like, each of which are “off-the-shelf” or downloadable software programs. The Web server platform (sometimes referred to as a “Web” site) supports files in the form of hypertext documents and objects. In the Internet paradigm, a network path to a server is identified by a so-called Uniform Resource Locator (URL). The World Wide Web is the Internet's multimedia information retrieval system. In particular, it is a collection of servers of the Internet that use the Hypertext Transfer Protocol (HTTP), which provides users access to files using Hypertext Markup Language (HTML).

[0020] A representative Web Server platform 12 comprises an IBM RISC System/6000 computer 18 (a reduced instruction set of so-called RISC-based workstation) running the AIX (Advanced Interactive Executive Version 4.1 and above) Operating System 20 and a Web server program 22, such as Netscape Enterprise Server Version 2.0, that supports interface extensions. The platform 12 also includes a graphical user interface (GUI) 24 for management and administration. The various models of the RISC-based computers are described in many publications of the IBM Corporation, for example, RISC System/6000, 7013 and 7016 POWERstation and POWERserver Hardware Technical Reference, Order No. SA23-2644-00. AIX OS is described in AIX Operating System Technical Reference, published by IBM Corporation, First Edition (November 1985), and other publications. While the above platform is useful, any other suitable hardware/operating system/web server combinations may be used.

[0021] The Web Server accepts a client request and returns a response. The operation of the server 22 is governed by a number of server application functions (SAFs), each of which is configured to execute in a certain step of a sequence. This sequence, illustrated in FIG. 2, begins with authorization translation (AuthTrans) 30, during which the server translates any authorization information sent by the client into a user and a group. If necessary, the AuthTrans step may decode a message to get the actual client request. At step 32, called name translation (NameTrans), the URL associated with the request may be kept intact or it can be translated into a system-dependent file name, a redirection URL or a mirror site URL. At step 34, called path checks (PathCheck), the server performs various tests on the resulting path to ensure that the given client may retrieve the document. At step 36, sometimes referred to as object types (ObjectType), MIME (Multipurpose Internet Mail Extension) type information (e.g., text/html, image/gif, etc.) for the given document is identified. At step 38, called Service (Service), the Web server routine selects an internal server function to send the result back to the client. This function can run the normal server service routine (to return a file), some other server function (such as a program to return a custom document) or a CGI program. The present invention primarily concerns the situation where the server function runs a CGI program resident on the Web server. At step 40, called Add Log (AddLog), information about the transaction is recorded. At step 42, called Error, the server responds to the client when it encounters an error. Further details of these operations may be found in the Netscape Web Server Programmer's Guide, Chapter 5, which is incorporated herein by reference.

[0022] Thus, the Web server 18 includes a known set of server application functions (SAFs). These functions take the client's request and other configuration data of the server as input and return a response to the server as output. Referring back to FIG. 1, the Web server 18 also includes an Application Programming Interface (API) 26 that provides extensions to enable application developers to extend and/or customize the core functionality thereof (namely, the SAFs) through software programs commonly referred to as “plug-ins.”

[0023] By way of additional background, the server stores variables in name/value pairs. The parameter block, or pblock, is a hash table keyed on the name string. The pblock maps these name strings onto their value character strings. A plug-in function uses parameter blocks to get, change, add and remove name/value pairs of data. A set of known parameter manipulating functions may be used to add, remove, edit and create name/value pairs, as more particularly described, for example, in the Netscape Programmer's Guide, discussed above. The pb_param structure is used to manage the name/value pairs for each client request, and the pb_entry structure creates linked lists of pb_param structures.

[0024] In the Netscape server, the Request->vars parameter block contains the server's working variables. The set of active variables changes as the different server methods are processed. The Request->headers parameter block contains the client's HTTP headers in the form {Name:value}. The Request->srvhdrs parameter block is the set of HTTP headers for the server to send back to the client. A request_header functions finds the parameter block that contains the client's HTTP headers. If the client sends to the server any HTTP headers along with its request, then these headers are placed into the environment, with the names of the environment variables being the names of the HTTP headers, prefixed with HTTP_. All letters in the name are changed to upper case and all hyphens are changed to underscore characters. As will be seen, the present invention extends the use of the request headers (normally headers sent by the browser) to act as a medium for transferring environment variables of any format (i.e. without the HTTP_prepended) to CGI programs.

[0025] Serving Common Gateway Interface (CGI) programs are an important part of the HTTP server function. CGI is a World Wide Web standard for extending the functionality of HTML. CGI involves the combination of a live Web server and external programming scripts. CGI programs are typically used to return dynamic information and to respond to HTTP browser input in HTML forms. The Netscape server passes only certain environment variables to the CGI program in order to save storage space and improve security. Thus, for example, the environment variable may contain the name and version of the software that the server is running under, the domain name or IP address of the server machine, the URL that individuals should use to access the server, and the like.

[0026] CGI programs usually run as child processes created under HTTP server processes. This known process is now described in conjunction with the process flow diagram shown in FIG. 3.

[0027] As illustrated there, the CGI process 50 will be run as a “child” to the HTTP server process 52. In particular, during the Web transaction, the server process 52 executes the AuthTrans, NameTrans, PathCheck and ObjType methods 54a-54ddescribed above with respect to steps 30, 32, 34 and 36 in FIG. 2. At this point in the transaction, the CGI process has not actually been created, although it is shown in the illustration. After executing steps 30, 32, 34 and 36, the service request is handled (which is step 38 in FIG. 2) using the Service method 54e. It is now assumed that the Web transaction involves a CGI script or program. In such case, the HTTP server Process 52 performs a func_exec( ) call to a CGI service method 56, called send-cgi. The send-cgi service method does a fork/exec, which is a Unix method for creating a new process. The fork creates a mirror process, which is the CGI process 50, and the exec is used to start this process with some other code, namely the Target CGI program 58. As a result of the fork/exec, the Target CGI program 58 is executed, and the results returned to the send-cgi service method 56. Thereafter, the HTTP server process returns control to the Addlog service method 54f. The Error service method 54gis then run to complete the server portion of the transaction.

[0028] According to the invention, the conventional send-cgi service method 56 is “encapsulated” between code that has been added in the HTTP server process 52 and code that has been added in the CGI child process 50. As used herein, the code added to the HTTP server process is a plug-in referred to herein as “env-send-cgi” and the CGI encapsulation code is a program referred to “setenv.cgi”. These programs provide a mechanism for setting dynamic, non-Netscape defined environment variables in the CGI process 50 without overriding or modifying the send-cgi server method.

[0029] The present invention is illustrated in a process flow diagram of FIG. 4. A comparison of the process flow diagrams in FIG. 3 (without the inventive technique) and FIG. 4 (with the technique included) illustrates the novel way in which the Netscape CGI service method (send-cgi) is encapsulated to provide a mechanism for setting dynamic, non-Netscape defined environment variables in CGI processes according to the invention. At the outset, the HTTP server process configuration file (obj.conf) must be modified, in effect, to override (but not replace) the send-cgi service method, which would normally be executed to carry out the CGI service request. Thus, according to the preferred embodiment of the invention, the HTTP server process is configured to override the send-cgi service method by adding into the HTTP server configuration file a load directive for the encapsulation plug-in env-send-cgi.

[0030] Now, as seen in FIG. 4, after the HTTP server process 52 has completed the execution of the AuthTran, NameTrans, ObjType and PathCheck methods 54a-54d, it runs the encapsulation plug-in “env-send-cgi” 55 instead of the normal send-cgi service method 56 (as in FIG. 3). After some initial processing (to override the CGI path name with the path name of the CGI process encapsulation program), the encapsulation plug-in env-send-cgi then performs a func_exec( ) call to run the HTTP server's original send-cgi method. The send-cgi service method initiates a fork/exec to create the CGI process 50, which has been modified according to the invention to include the CGI process encapsulation program setenv.cgi. Thus, instead of creating the CGI process and then running the Target CGI program directly, the send-cgi service routine calls the CGI process encapsulation program setenv.cgi provided 57 by the present invention. The encapsulation CGI code sets environment variables and executes the target CGI program 58. After the CGI processing is complete, as will be described, control is returned back to the send-cgi method 56 of the HTTP server process. Send-cgi 56 returns control back to the env-send-cgi plug-in 55, which restores parameter blocks and returns control back to the HTTP server (to complete the AddLog and Error methods 54f-54g).

[0031] A more detailed description of the operations provided by the encapsulation routines is now provided and illustrated in the flowchart of FIG. 5. The inventive process begins at step 60 by adding a load directive for the server configuration file (obj.conf) for the plug-in env-send-cgi. In step 62, the entry for send-cgi in the configuration file is replaced with env-send-cgi. Steps 60 and 62 represent a configuration operation in which the server is configured to override the send-cgi service method. These steps will be effected “off-line” (i.e. outside of the context of a given Web transaction). Now, assuming that a Web transaction is in process and the first four steps of the server operation have occurred, the method continues at step 64 by having env-send-cgi get the target CGI program's fully-qualified path name from the request->vars parameter block. At step 66, env-send-cgi stores the CGI path in a predetermined manner so that it will later be visible in the child CGI process as a “mangled” environment variable. This is accomplished, for example, by having env-send-cgi insert a name/value pair (e.g., name=CGIENVPATH and value=the target CGI program's path name) into the request header parameter block of the server. At step 68, the plug-in overrides the CGI path name with the path of the CGI process encapsulation program (setenv.cgi). Thereafter, at step 70, the plug-in calls the server's real send-cgi method. This operation calls the “/usr/bin/setenv.cgi” program currently in the “path” variable, and this is represented at step 71 in the flowchart. Thus, steps 64, 66, 68 and 70 executes env-send-cgi to cause send-cgi to execute the encapsulation CGI setenv.cgi.

[0032] As noted above, the encapsulation CGI setenv.cgi sets environment variables and executes the target CGI program in its place. This operation begins at step 72 by having setenv.cgi scan the environment for variables prepended with either string “HTTP_CGIENV_” or “HTTPS_CGIENV_”. For each variable that meets this criteria (i.e. being prepended by either string), setenv.cgi continues at step 74 by stripping off the prepended portions of the string (namely, “HTTP_CGIENV_” or “HTTPS_CGIENV_” as the case may be) and storing the remainder of the string back into the environment. Thus, what remains after step 74 is the original “value” of the name/value pair in unmangled form. This value is the environment variable. At step 76, setenv.cgi gets the target CGI program path from the environment. At step 78, setenv.cgi sets the working directory according to the CGI program path. At step 80, setenv.cgi swaps the program path argument (arg 0) according to the CGI program path. The setenv.cgi code then executes the real target CGI program on top of the current process at step 82.

[0033] After the CGI program exits and the forked CGI process is terminated, send-cgi continues. This is step 84 in the flowchart. When send-cgi returns at step 86, control passes back to env-send-cgi. At step 88, env-send-cgi restores parameter blocks and returns control back to the server. This completes the processing.

[0034] Thus, according to the present invention, with the plug-in (env-send-cgi) and the CGI process encapsulation code (setenv.cgi) installed and configured, any server plug-in called during the AuthTrans, NameTrans, PathCheck or ObjectType steps can set environment variables in CGI processes. This is done simply by inserting “name value” pairs into the request->headers parameter block with the environment variable prepended by the marker, e.g., the string “CGIENV_”. This process works because when Netscape send-cgi executes the CGI's process, it normally “mangles” the resulting environment variable by prepending “HTTP_” in front of the initial variable name. The present invention, in effect, inserts another name into the request header block to “mark” or tag the environment variable so that it can be “demangled” (by removing the marker inserted by the present invention as well as the “HTTP_” portion inserted by send-cgi).

[0035] The following are representative process and code snippets used to implement the flowchart discussed above in FIG. 5:

[0036] Step 60 adds a load directive for the plug-in:

[0037] “Init fn=load-modules shlib=/usr/lib/libcgienv.a funcs=env-send-cgi”

[0038] Step 62 replaces “send-cgi”with “env-send-cgi”:

[0039] <Object name=“cgi”>

[0040] ObjectType fn=“force-type” type=“magnus-internal/cgi”

[0041] Service fn=“env-send-cgi”

[0042] </Object>

[0043] Step 64 causes the plug-in (env-send-cgi) to get the target CGI program's fully qualified path name from the request →vars parameter block

[0044] pszTargetCGI=pblock_findval(“path”, request→vars);

[0045] At step 66, the plug-in stores the CGI path so that it will be visible in the child CGI process as a mangled environment variable:

[0046] pblock_nvinsert(“CGIENVPATH”,pszTargetCGl,request→headers);

[0047] At step 68, the plug-in overrides the CGI path name with the CGI process encapsulation program (setenv.cgi) path:

[0048] param_free(pblock)remove(“path”,request→vars));

[0049] pblock_nvinsert(“path”,“/usr/bin/setenv.cgi”,request→vars)

[0050] At step 70, the plug-in calls the Netscape “send-cgi”method, which (at step 71) will call the “/usr/bin/setenv.cgi” program currently in the “path” variable:

[0051] pblock_copy(param,pb_send_cgi);

[0052] param_free(pblock)_remove(“fn”,pb_send_cgi));

[0053] pblock_nvinsert(“fn”,“send-cgi”,pb_send_cgi);

[0054] retcode=func_exec(pb_send_cgi,sn,rq);

[0055] At this point, setenv.cgi processing occurs.

[0056] After the CGI processing is complete and “send-cgi” returns, control is passed back to the “env-send-cgi” plug in at step 86.

[0057] The plug-in restores the parameter blocks and returns control back to the Netscape server at step 88.

[0058] pblock_free(pb_send_cgi);

[0059] /* Now restore the request→vars “path” for logging purposes */

[0060] param_free(pblock_remove(“path”,request→vars));

[0061] pblock_nvinsert(“path”,targetCGl,request→vars);

[0062] return(retcode);

[0063] This completes the main processing loop. The following describes the encapsulation CGI “setenv.cgi” operation, which sets environment variables and executes the target CGI program in its place (current process).

[0064] At step 72, the code setenv.cgi scans the environment for variables prepended with either strong “HTTP_CGIENV_” or “HTTPS_CGIENV_”. For each variable that meets this criteria, at step 74, the original string is stored back into the environment in unmangled form.

[0065] UnMangledVariable=MangledVariable+strlen(“HTTP_CGIENV_”;

[0066] or

[0067] UnMangledVariable=MangledVariable+strlen(“HTTPS_CGIENV_”);

[0068] putenv(UnMangledVariable);

[0069] At step 76, setenv.cgi gets the target CGI program path from the environment:

[0070] CGlpath=getenv(“HTTP_CGIENVPATH”)

[0071] At step 78, setenv.cgi sets the working directory according to the CGI program path:

[0072] strcpy(CGldir,CGlpath);

[0073] *(strrchr(CGldir,‘/’))=‘/0’;

[0074] chdir(CGldir);

[0075] At step 80, setenv.cgi swaps the program path argument (argv.0”) according to the CGI program path:

[0076] argv[0]=CGlpath;

[0077] At step 82, setenv.cgi executes the real target CGI program on top of the current process:

[0078] execv(CGlpath,argv);

[0079] At step 86, when the target CGI program completes the execution, the CGI process will end, and the Netscape server process will continue (“send-cgi” will gain control, then return back to “env-send-cgi”).

[0080] When libcgienv.a and setenv.cgi installed and configured, any Netscape server plug-in can set environment variables in CGI processes. This can be done simply by inserting name value pairs into the request→headers parameter block with the environment variable prepended by the string “CGIENV_”.

[0081] util_springf(cgiEnvName,“%s%s”,“CGIENV_”,envVarName):

[0082] param_free(pblock_remove(cgiEnvName,request→srvhdrs));

[0083] pblock_nvinsert(cgiEnvName,envVarValue,request→srvhdrs);

[0084] One of the preferred implementations of the env-send-cgi plug-in and the CGI process encapsulation (setenv.cgi) is as a set of instructions (program code) in a code module resident in the random access memory of the computer. Until required by the computer, the set of instructions may be stored in another computer memory, for example, in a hard disk drive, or in a removable memory such as an optical disk (for eventual use in a CD ROM) or floppy disk (for eventual use in a floppy disk drive), or downloaded via a computer network. In addition, although the various methods described are conveniently implemented in a general purpose computer selectively activated or reconfigured by software, one of ordinary skill in the art would also recognize that such methods may be carried out in hardware, in firmware, or in more specialized apparatus constructed to perform the required method steps.

[0085] Further, although the invention has been described in terms of a preferred embodiment in a specific HTTP Web server, those skilled in the art will recognize that the invention can be practiced, with modification, in other and different HTTP servers that provide a plug-in application programming interface (API). Moreover, while the invention has been specifically described in the context of passing environment variables into CGI programs, this is not a limitation of the invention either. The inventive technique, namely configuring the HTTP server to override a service method and then encapsulating the service method between a first program, executable in the child process, and a second program, executable in the server process that launches the child process, may apply to other service methods besides CGI programs.

[0086] Having thus described our invention, what we claim as new and desire to secure by letters patent is set forth in the following claims: