Next Previous Contents

3. Administration

The administration of the Pi3Web server is based on Win32 native applications build on the same Pi3 component technology as the Pi3Web server itself.

3.1 Local Administration

The Pi3Web Server running on Win32 systems has a built in administration application. Since this program is executed within the account of the current desktop user, no authentication is required to gain access to it. For other platforms the configuration files are edited manually since this is the common way on that systems.


The following functionality is available when using the administration application (brief overview):


to start and stop the server. If the server status is modified outside of this program, you can use 'Refresh' to update the buttons.


to set general server options. These options determine the URL used to access the website. If this website will be accessed from other computers over the Internet or an Intranet using a hostname or alias, an appropriate DNS entry must exist. The administrator's e-mail address is appended to error messages or server-side includes as the contact person for the website.


to set factors which effect server performance. Connections (number of server threads), thread reuse, send and receive timeouts should only be modified by advanced users. Connection Keep-Alive optimizes server performance by reusing connections across multiple requests.


to control how URL's are mapped to resources on your computer and the authentication associated with them.


to add and delete authentication realms and to associate users with realms. You can use the Mappings page to associate URL paths with the authentication realms that you define here.

MIME Types

to control the MIME types associated with files sent to browsers from the server.


to make the server create logfiles with statistics on the server's operation and people who have visited the website.Specifying too many logfiles will adversily effect server performance.Interfaces to manage supplementary TCP/IP interfaces listening for connections. Needs performance option 'reuse threads' enabled.

Non IP Virtual Hosts

to configure Non-IP virtual hosts, i.e. virtual hosts which do not have a dedicated IP address.

IP Virtual Hosts

to configure IP based virtual hosts, i.e. virtual hosts which have a dedicated IP address.

Directory Indexing

to set the general layout, formatting style and sorting options of directory indexes.


to adjust several advanced HTTP settings. The index files are used for response, if they exist in web directories. The POST-handler enables multipart-form upload acc. to RFC1867. Consider that POST, PUT and DELETE may affect server security in an untrusted environment without additional authentication.


to enable SSL, generate server keys and certificate and to set SSL options such as SSL/TLS version, path and filename of server private key and certificate, client certificate verification depth, CA certificate path and filename, advanced and debug options, cipher list

3.2 Remote Administration Client

For the Pi3Web Server 2.0.3 theres a remote administration client available running as a Win32 application. The utility may also be used cross-platform, i.e. you may configure a server running on Linux using the remote administration client on Win32. Note, that the default configuration files for POSIX platforms (Pi3Web/Conf/Features.pi3) is not generated to be used with an administration tool. Refer to the next section or wait for the next server release in order to make use of this possibility.


Before starting with remote administration you should plan, how the remote administration is implemented within the operating concept of your server. The main topics are:


It is recommended to use a separate network interface (i.e. IP address) for remote administration if available. The physical separation of the remote administration from the server transport provides the best security. This can be used, e.g. if the server is accessed through DSL or cable modem and the remote administration is used through a LAN, e.g. a home network. If a separate IP address or port is used for remote administration, prepare the required other components, like router or firewall accordingly.


Since the configuration data is transfered over a network, the channel should be secured by transport layer security (SSL, TLS), if the network is accessed by untrusted parties. You can use the existing SSL layer of the server or setup a separate SSL channel for remote administration.


The authentication of the remote user ensures, that only authorized persons can perform configuration changes remotely. There are different authentication schemes available. The HTTP Basic Authentication should be used over a secure connection only because the password is not encrypted. The HTTP Digest Authentication prevents submission and local storage of unencrypted password data by using MD5 hash values instead. Unencrypted password data should never be stored at the client computer.

Based on this, for the remote administration it is recommended to use always transport layer security and store the password data at the client side only, if HTTP Digest authentication is used.

Preparing the Pi3Web Server

The following steps are performed with the local administration application in order to prepare the Pi3Web server for remote administration:

  1. Check your server version, the remote administration is available for Pi3Web 2.0.3 or greater. If required, upgrade to the appropriate server version
  2. Switch on the 'Remote Administration' option at the 'General' tab of the local administration application
  3. Optional: Add a new realm 'Administration' of type 'Digest' and the new username/password at the 'Users' tab
  4. Optional: Add a new TCP/IP or SSL interface for the IP address and port of the remote administration. Generate a server key for a new SSL interface.
  5. Save the changes you made and restart the server

Preparing the Remote Administration Client

The following steps are performed with the remote administration application in order to prepare the Pi3Web server for remote administration:

  1. Install the remote administration client (Pi3Admin.exe)
  2. During installation the remote administration connection is configured. Enter the hostname/IP address and the port of the remote connection to your Pi3Web server and whether SSL is used. Remote administration connections can also be added, after the installation of the Pi3Admin application has been finished.
  3. Enter the username for remote administration and - optional, only if it shall be stored - the password
  4. Select the administration pages (tabs), which shall be available for remote administration. Note, that some configuration parameters may require add a new remote administration connection or even disable the remote administration permanently

Connect with the Remote Administration Client

The following steps are performed with the remote administration application in order to connect to the Pi3Web server for remote administration:

  1. Start the remote administration client by clicking on the program manager icon created for the remote connection to your Pi3Web Server.
  2. Enter the username and password (the login dialog will not appear, if the information is stored at the client side and the authentication suceeds).
  3. The remote administration console appears and can be used as the local administration program.

Note, as an alternative you can also start the program from the command line:

cd Pi3Admin/bin
Pi3Admin /CONFIGURE ../Conf/remote_address.pi3


cd Pi3Admin/bin
Pi3 ../Conf/remote_address.pi3

where remote_address is the name of the configured remote connection.


These are the different error messages, which are displayed, if a remote administration session couldn't be performed and a description of the most probable causes.

  1. "Could not open configuration file remote_address.pi3" - The command line for starting the remote administration was wrong or no configuration file exists.
  2. "Could not open connection to server remote_address for configuration download" - The remote Pi3Web server is offline or the connection data (hostname/IP address or port) is wrong.
  3. "Could not open connection to server remote_address for configuration upload" - The remote Pi3Web server went offline before the changed configuration has been saved.
  4. "Error reading response headers from remote server remote_address" - The Pi3Web SSL server is offline or the client requires SSL and the server doesn't support it (or vice versa) or you tried to connect to a TCP/IP service, which is not an HTTP server.
  5. "Received error response from server: 401 Unauthorized" - The given user name or password is wrong or does not exist for the realm 'Administration' at the remote Pi3Web Server.
  6. "Received error response from server: 500 Internal Error" - Reading the configuration file at the remote Pi3Web Server failed. Check the file permissions.
  7. "Response from remote server seems not to contain a valid Pi3 config file" - Syntax error in the downloaded configuration from the remote Pi3Web Server. Check the server version and the contents of the used configuration file at the remote server.
  8. "The version of the loaded configuration file is version. This Pi3Admin software supports only version version." - The version of the remote configuration file is not compatible with the version of the remote administration client. Check the release notes and the documentation of both programs for more information.

Next Previous Contents