Creating and Using Pivotal Web Server Instances

Note: This product has been discontinued. Technical Guidance ends July 15th 2018.

To start using Pivotal Web Server, you explicitly create a new instance after you install it. An instance is not created for you by default.

Subtopics

Description of Pivotal Web Server Instances

Create Pivotal Web Server Instances

newserver Prompts and Command Reference

Unix: Start and Stop Pivotal Web Server Instances

Windows: Start and Stop Pivotal Web Server Instances

httpdctl Reference

Serve a Sample HTML File from Your Pivotal Web Server Instance

Description of Pivotal Web Server Instances

A Pivotal Web Server instance is a complete, discrete HTTP server configuration.

You can create multiple instances that you can run simultaneously on the same computer if you do not use the same ports in two different instances. For example, the default HTTP listening port on Unix is 80, and only one instance on any computer is allowed to communicate on port 80 at any one time. So if you wanted to have two Pivotal Web Server instances running at the same time on the same Unix computer, you configure one instance to use a port other than 80.

After you create an instance, its corresponding directory contains subdirectories that in turn contain all the data required to run a given Pivotal Web Server instance. This data includes configuration information and all other data that is associated with that instance’s configuration. For example, assume you installed Pivotal Web Server in /opt/pivotal/webserver and create an instance called myserver:

prompt$ cd /opt/pivotal/webserver/myserver
prompt$ ls
bin  cgi-bin  conf  ftpdocs  htdocs  logs  proxy ssl  var

The conf directory contains the Pivotal Web Server configuration files, such as httpd.conf. The bin directory contains the startup script used to start and stop the myserver instance (httpdctl). Each of these directories is specific to the myserver instance. Each instance you create will have a similar set of directories.

Create Pivotal Web Server Instances

Create Instances Using the newserver Command

You create a new Pivotal Web Server instance with the newserver command. The command creates a new directory that contains the instance-specific configuration files.

The newserver command format depends on your operating system:

  • newserver : Perl script for Unix operating systems.
  • newserver.ps1: Powershell script for Windows operating systems.

The command-line options for the two flavors are exactly the same. Where appropriate, the following procedure calls out the different usage depending on whether you are on Unix or Windows.

Prerequisites

  • Complete the appropriate procedure in Installing Pivotal Web Server.
  • As of version 5.2 of Pivotal Web Server, you must use Windows PowerShell to execute Pivotal Web Server scripts on Windows computers. See the prerequisites section of Windows: Install Pivotal Web Server from a ZIP File for information on installing PowerShell (if it is not already installed on your Windows computer) and enabling it for script processing.

Procedure

  1. Log on to your computer as root (Unix) or the Administrator user (Windows) and start a terminal (Unix) or PowerShell window (Windows).

    To start a PowerShell window, go to Start > All Programs > Accessories > Windows PowerShell, then right-click on Windows PowerShell and select Run as Administrator.

  2. Change to the directory in which you installed Pivotal Web Server. For example, on Unix:

    prompt# cd /opt/pivotal/webserver 
    
  3. Run the newserver command to create the new instance; the command prompts you for information about the new server.

    The only required command option is --server, with which you specify the name of your Pivotal Web Server instance. On Unix, use the Perl flavor; for example:

    prompt# ./newserver --server=myserver 
    

    On Windows, use the PowerShell script:

    PS prompt> .\newserver.ps1 --server=myserver 
    

    In both preceding examples, the way you specify the options is exactly the same. In the examples, the new instance is called myserver and its server directory is /opt/pivotal/webserver/myserver.

    For additional options, see newserver Prompts and Command Reference.

  4. Enter values for the newserver prompts as the command requests information about your new instance. You can use the default values for many of the prompts, or even leave them blank.

    newserver Prompts and Command Reference provides additional information about the prompts.

What to do next

Windows - Create and Modify Instances

The MSI installer for Microsoft Windows installs the Pivotal Web Server Configurator with the application.

Creating a Web Server Instance

  1. Click the Start button > All Programs > Pivotal > Pivotal Web Server Configurator.

    The application opens and displays the list of existing Web Server instances.

  2. Click the Add button.

    The Basic Settings window opens.

  3. Complete the following fields:

    • Enter a server name. The server name identifies the Web Server instance locally.
    • Enter the port number for HTTP listening.
    • Enter the host name. The host name identifies the web server instance on your network or the Internet.
    • Accept the default server location, or browse to and select a new location.
  4. Click the Next button.

    The SSL Settings and Administrator Email page opens.

  5. Optional. Enable SSL:

    • Select the Enable SSL checkbox if you are enabling SSL.
    • Enter the port for HTTPS listening. The default value is 443.
    • Browse to and select a SSL certificate file location. For information about configuring SSL between Pivotal Web Server and Pivotal tc Server, see Configure SSL Between Pivotal Web Server and Pivotal tc Server.
    • Browse to and select a key file location.

    If you do not want to enable SSL, then leave the checkbox cleared.

  6. Enter the Web Server administrator email address.

  7. Click the Next button.

  8. Review the installation configuration list.

  9. Click the Finish button when you are ready to proceed.

    Note: The configurator does not display a progress bar as it creates the new instance.

    The configurator displays the new Web Server instance in the list.

  10. Click the Install button to create a Windows service for the instance.

Starting and Stopping a Web Server Instance

  1. Click the Start button > All Programs > Pivotal > Pivotal Web Server Configurator.

    The application opens and displays the list of existing Web Server instances.

  2. Select the instance that you want to start or stop.

  3. Start or stop the instance.

    • Click the Start button to start the Windows service for the instance.
    • Click the Stop button to stop the Windows service for the instance.

Removing a Web Server Instance

  1. Click the Start button > All Programs > Pivotal > Pivotal Web Server Configurator.

    The application opens and displays the list of existing Web Server instances.

  2. Select the instance that you want to remove.

  3. Click the Remove button.

    The configurator stops the instance Windows service, if started, and removes the instance from your hard drive.

newserver Prompts and Command Reference

The newserver command has a number of options and prompts, as described in the two tables that follow.

The newserver command format depends on your operating system:

  • newserver : Perl script for Unix.
  • newserver.ps1: PowerShell script for Windows.

The command-line options for the two flavors are exactly the same.

Table 1. Options of the newserver Command
Option Description Required?
--server=servername Name of the new Pivotal Web Server instance. The value of this option becomes the name of the directory that contains the instance configuration files, and by default is the name of the host.

The value of servername must be a valid DNS value and consist only of ASCII letters, digits or the dash character. Illegal characters include but are not limited to control characters below ASCII 32 as well as the following symbols: < > : " / \ | ? *.

If you want to use an internationalized (i18n) name for the instance directory, you must enter the correct Punycode domain name provided by the registrar for the actual hostname. Do this by either specifying the --set HostName=punycode-hostname option at the command-line or entering the value interactively when the newserver command prompts you for the hostname.

Yes.
--httpddir=httpddir Directory that contains the Apache HTTP binaries.

The default value is rootdir/httpd-httpdver , such as /opt/pivotal/webserver/httpd- 2.4.10 -64.

No.
--httpdver=httpdver Version of the Apache HTTP binaries you want your instance to use.

The default value is 2.4 , which is a symbolic link to the actual installed version of the binaries, such as 2.4.10 .

No.
--mpm=mpm Specifies the type of multi-processing module (MPM) that the instance uses. Valid values are:
  • worker: Threaded MPM, ideal if you need a great deal of scalability. By using threads to serve requests, the instance can serve many requests with fewer system resources than a process-based server.
  • prefork: Non-threaded, pre-forking MPM if you require stability or compatibility with older software.
  • event: Less proven but higher-efficiency asynchronous connection-keepalive MPM. The event MPM offers little benefit for HTTPS connections, but is able to handle more simultaneous kept-alive and pending HTTP connections.

The default value is worker.

No.
--overlay Specifies that, if serverdir exists, you want to overwrite the existing files with new ones. No.

If you do not specify this option, and serverdir exists, the newserver command returns an error and suggests you specify a unique name and directory location for the new instance.

--quiet Specifies that the newserver command should use default values for all prompts. No.

If you do not specify this option, newserver interactively prompts for all answers.

--rootdir=rootdir Directory that contains the httpd- 2.4 .version directory, which in turn contains the Apache HTTP binaries.

The default value is the current directory.

No.
--serverdir=serverdir Directory in which you want the new instance directory to be created.

The default value is rootdir.

No.
--set token=value Specifies one or more tokens for which you would like to specify a custom value. The tokens are variables in the templates used to create new Pivotal Web Server instances and correspond to a directive, or part of a directive, in the new instance’s configuration. Each available token has a default value (listed below) that is automatically configured if you do not override it using the --set option.

You can specify the following tokens; note that the token names are case-sensitive:

  • User: User that the Pivotal Web Server processes run as. Corresponds to the User directive in conf/httpd.conf. Default value is pwshttpd.
  • Group: Group to which the user who runs the Pivotal Web Server processes belongs. Corresponds to the Group directive in conf/httpd.conf. Default value is pwshttpd.
  • Port: HTTP port that the Pivotal Web Server instance listens to. Corresponds to the port number in the Listen directive in conf/httpd.conf. Default value is 80.
  • SSLPort: HTTPS port that the Pivotal Web Server instance listens to for secure communications. Corresponds to the port number in the Listen https directive in conf/extras/httpd-ssl.conf. Default value is 443.
  • HostName: Name of the host that the instance uses to identify itself. Corresponds to the hostname part of the ServerName directive in the conf/httpd.conf file. Default value is the value you specified for the required --server option.
  • ServerAdmin: Email address of the administration user who should get emails when there are problems with the instance. Corresponds to the ServerAdmin directive in the conf/httpd.conf file. Default value is webmaster@HostName..

The following example shows how to specify that the new Pivotal Web Server instance run as the newhttpd user in the newhttpd group:

prompt# ./newserver --server=myserver --set User=newhttpd --set Group=newhttpd
No.
--sourcedir=sourcedir Name of the directory that contains the template that newserver uses to create the new Pivotal Web Server instance.

The default value is httpdir/_instance.

No.

Table 2. newserver Prompts
Prompt Description
Enable SSL and create a default key [y/n]? Enabling SSL provides secure communication between client and server by allowing mutual authentication; the use of digital signatures for integrity; and encryption for privacy. If you answer yes, you are later asked for information that will be used to create a certificate.
Server hostname (e.g. www.example.com) [myserver]? Name that the Pivotal Web Server instance uses to identify itself. If your host does not have a registered DNS name, enter its IP address. The default value is the value you entered for the --server option.
Administrator email [webmaster@myserver]? Email address to which Pivotal Web Server instances send problems. This address appears on some instance-generated pages, such as error documents.
Port for http:// traffic [80]? HTTP port to which the Pivotal Web Server instance listens. Default value is 80 when running the newserver command as the root user on Unix, 8080 otherwise.
Port for https:// SSL traffic [443]? HTTPS port to which the Pivotal Web Server instance listens. Default value is 443 when running the newserver command as the root user on Unix, 8443 otherwise.
If you previously specified that you want to enable SSL… The newserver command prompts you for information required to create the private key, such as the size of the SSL RSA key in bits and the PEM pass phrase you specify when you start the instance.

You also are prompted to enter information for your certificate. The information is mostly about your Distinguished Name, or DN, that will be incorporated into your certificate request. As indicated, some fields have default values. You can also leave some fields blank by entering a ’.’ (period.)

When newserver completes, it generates the following SSL files in the ssl subdirectory of the instance directory:

  • instance_name.key: Unencrypted private key. The file has a permission code of 0600 for additional security.
  • instance_name.pem: DES 3 encrypted private key.
  • instance_name.csr: Certificate-signing request. Submit this file to the Certificate Authority.
  • instance_name.crt: Self-signed certificate. Replace this certificate with a signed certificate by the CA.
**Important:** Be sure to record the passphrase to decrypt the *.pem file and back up the file. Never transmit the .key file or cause it to be readable by others.

Unix - Start and Stop Pivotal Web Server Instances

You interactively start, stop, or restart a Pivotal Web Server instance on Unix with the httpdctl shell script in the bin directory of the instance.

Warning: You always use the start script in the bin of the instance directory, such as /opt/vwmare/pivotal-web-server/myserver/bin. Do not use the start script in the httpd- /bin sub-directory of the main installation directory.

You can also install a Pivotal Web Server instance as a Unix service so it automatically starts and stops when the operating system itself is started and stopped. If you install it as a service, you can also start and stop the service by using the /etc/init.d/service-name script. For more information, see Installing Pivotal Web Server Instances as Unix Services.

Prerequisites

Procedure

  1. Log in to your Unix computer as the root user.
  2. Start a terminal window and change to the bin sub-directory of your Pivotal Web Server instance’s root directory. For example, if you created an instance called myserver that lives in the installation directory /opt/pivotal/webserver:

    prompt# cd /opt/pivotal/webserver/myserver/bin
    
  3. Start the instance using the ./httpdctl start command:

    prompt# ./httpdctl start
    

    You should see a message as follows:

    Starting Apache: 
    Server started OK
    
  4. To test that the Pivotal Web Server instance actually started, navigate to the http://host:port URL in your browser, where host refers to the host computer (you can use localhost if your browser is on the same computer) and port refers to the HTTP listen port number you provided when you created the instance. The default value is 80

    For example, if you are using the default ports on your local computer, you can use this URL:

    http://localhost:80
    

    If the instance started successfully, you should see the Welcome page.

  5. To get status about the instance:

    prompt# ./httpctl status
    
  6. To stop the instance immediately, even if there are current connections in use:

    prompt# cd /opt/pivotal/webserver/myserver/bin
    prompt$ ./httpdctl stop
    

    To stop the instance gracefully:

    prompt$ ./httpdctl gracefulstop
    

See httpdctl Reference for the full list of available httpdctl commands.

What to do next

Installing Pivotal Web Server Instances as Unix Services

You can install a Pivotal Web Server instance as a system service on Unix, Linux, so it automatically starts and stops when the operating system itself starts and stops. If you install it as a service, you start and stop the service by using the /etc/init.d/ServiceName script.

Procedure

  1. Log in to your computer as the root user.
  2. Start a terminal window and change to the bin sub-directory of your Pivotal Web Server instance’s root directory. For example, if you created an instance called myserver that lives in the installation directory /opt/pivotal/webserver:

    prompt# cd /opt/pivotal/webserver/myserver/bin
    
  3. Install the instance as a service using the ./httpdctl install command:

    prompt# ./httpdctl install
    

    You should see the following output:

    Installing Pivotal httpd myserver
    as the unix service pivotal-httpd-myserver
    

    The display name for the service name is pivotal httpd instance_name. The service name is the display name, with spaces replaced by dashes: pivotal-httpd-instance_name.

  4. After creating the service, you can control it (1) with the system-config-services GUI utility, (2) by running the bin/httpdctl shell script from the instance directory, or (3) by running the /etc/init.d/ServiceName script, passing it the same commands as httpdlctl. For example, to start the myserver instance:

    prompt# /etc/init.d/pivotal-httpd-myserver start
    
  5. To uninstall the instance as a Unix service:

    prompt# ./httpdctl uninstall
    

Windows - Start and Stop Pivotal Web Server Instances

You start, stop, or restart a Pivotal Web Server instance on Windows by first installing it as Windows service using the httpdctl.ps1 PowerShell script in the bin directory of the instance directory, and subsequently using the Windows Services console to start or stop it.

Warning: You always use the start script in the bin of the instance directory, such as c:\opt\vmware\pivotal-web-server\myserver\bin. Do not use the start script in the httpd- \bin sub-directory of the main installation directory.

Prerequisites

  • Complete the appropriate procedure in Create Pivotal Web Server Instances.
  • As of version 5.2 of Pivotal Web Server, you are required to use Windows PowerShell to execute Pivotal Web Server scripts on Windows computers. See the prerequisites section of Windows: Install Pivotal Web Server from a ZIP File for information on installing PowerShell (if it is not already installed on your Windows computer) and enabling it for script processing.

Procedure

  1. Log in to your Windows computer as the Administrator user and start a PowerShell window by going to Start > All Programs > Accessories > Windows PowerShell, then right-clicking on Windows PowerShell and selecting Run as Administrator.
  2. Change to the bin subdirectory of the root directory for the Pivotal Web Server instance. For example, if you created an instance called myserver that lives in the installation directory c:\opt\vmware\pivotal-web-server: pre PS prompt> cd c:\opt\vmware\pivotal-web-server\myserver\bin

  3. Install the instance as a Windows service by running the httpdctl.ps1 install command:

    PS prompt> .\httpdctl.ps1 install
    

    The display name for the service name is pivotal httpd instance_name. The service name is the display name, with spaces removed: pivotal-httpd instance_name.

    After installing the service, you can control and further configure the service in several ways:  (1)  httpdctl command options, (2) the Windows Services console, or (3) the sc command

  4. To test that the Pivotal Web Server instance actually started, navigate to the http://host:port URL in your browser, where host is the host computer (you can use localhost if your browser is on the same computer), and port is the HTTP port number you provided when you created the instance. The default value on Windows is 80.

    For example, if you are using the default ports on your local computer, use this URL:

    http://localhost:80
    

    If the Pivotal Web Server instance started successfully, you should see the Welcome page.

  5. To get status about a running Pivotal Web Server instance, execute the following command:

    PS prompt> .\httpdctl.ps1 status
    
  6. To uninstall the Pivotal Web Server instance as a Windows service, use the following command:

    PS prompt> cd c:\opt\vmware\pivotal-web-server\myserver\bin
    PS prompt> .\httpdctl.ps1 uninstall
    

See httpdctl Reference for the full list of available httpdctl commands.

What to do next

httpdctl Reference

Use the httpdctl script to control a Pivotal Web Server instance: start ‘n’ stop it, install it as a service, and so on. The script is located in the bin directory of the instance directory, such as /opt/pivotal/webserver/myserver/bin.

The httpdctl script format depends on your operating system:

Script commands are the same for both. Commands are described in the following table.

Table 3. httpdctl Script Commands
Command Description
start Starts the Pivotal Web Server instance. If the instance is already running, the command returns an error.
stop Forcibly stops the Pivotal Web Server instance. All currently opened connections are aborted.
gracefulstop Gracefully stops the Pivotal Web Server instance, which means that the script waits until all currently open connections are closed rather than aborting them forcibly.
restart Restarts the instance. If the instance was not originally running, the script starts it. If the instance was not originally running, the script starts it. The script also runs a configtest before starting the instance.
graceful Gracefully restarts the instance. If the instance is not running, it is started. This command differs from a normal restart in that currently open connections are not aborted. A side effect is that old log files will not be closed immediately. This means that if you use this command in a log rotation script, a substantial delay may be necessary to ensure that the old log files are closed before processing them. This command runs a configtest before starting the instance.
status Displays basic status information about the instance, such as whether it is running and its process id (PID) if so.
install Installs the instance as a service on Windows, Unix, and Linux.

After installing the service on Windows, you use the Windows Services console or the sc command to start, stop, and restart the Pivotal Web Server instance, and configure whether the service starts automatically when Windows starts, and so on. For more information about the the sc command, see http://technet.microsoft.com/en-us/library/bb490995.aspx

On Unix, the instance is installed as a script file in the /etc/init.d directory with name pivotal-httpd-instance_name . The service automatically starts and stops when Unix is started or stopped.

uninstall Uninstalls the instance as Windows, Unix, or Linux service. On Windows, the instance is removed from the Service registry. On Unix, the command deletes the /etc/init.d/pivotal-httpd-instance_name script file.
configtest Runs a syntax test against the configuration files, such as conf/httpd.conf. The script parses the configuration files and either reports Syntax OK or outputs detailed information about the particular syntax error.

Serve a Sample HTML File from Your Pivotal Web Server Instance

After you install Pivotal Web Server and create an instance, you can use it to host your entire Web site. This section does not describe the entire process; rather, it simply shows how to serve an HTML file from the default document root of your instance.

Prerequisites

  • Create and start a Pivotal Web Server instance. See Create Pivotal Web Server Instances.
  • Create or download one or more sample HTML pages that you want to serve from the instance.

Procedure

  1. Open the configuration file for your Pivotal Web Server instance and make note of the value of the DocumentRoot directive, which is the directory out of which the instance serves your documents. By default, Pivotal Web Server takes all requests from this directory.

    The configuration file is called httpd.conf and is located in the INSTANCE-DIR/conf, such as /opt/pivotal/webserver/myserver/conf/httpd.conf. The DocumentRoot directive looks like the following:

    DocumentRoot "/opt/pivotal/webserver/myserver/htdocs" 
    
  2. Copy your sample HTML pages to the document root.

    For example, if you have a hello.html page in the /home/samples directory that you want to serve up:

    prompt# cp /home/samples/hello.html /opt/pivotal/webserver/myserver/htdocs
    
  3. Invoke the HTML page in your browser using the Pivotal Web Server instance.

    For example, if your browser is running on the same computer as Pivotal Web Server and the instance is listening at the default port 80, the URL is as follows:

    http://localhost/hello.html
    

    Because the instance is using the default port of 80, you do not have to explicitly specify it in the URL. If you set a different port, such as 8000, then the URL would be:

    http://localhost:8000/hello.html
    

    You should see your hello.html page in your browser.

  4. You can create a directory hierarchy under the document root to better organize your HTML pages.

    For example:

    prompt# cd /opt/pivotal/webserver/myserver/htdocs
    prompt# mkdir fun
    prompt# cp /home/samples/hello.html fun
    

    The URL to invoke the HTML page would now be:

    http://localhost/fun/hello.html
    

What to do next