How To Configure Pi³Web: Tips and Tricks

4. Tips and Tricks

This section contains some helpful additional information in a Q&A style. Some of these tipps are for advanced users only, i.e. you should not try them out and rather continue using the administration GUI if you aren't absolutely sure, what you want to do and how it works.

Why didn't you create a web interface for the administration console?

There are different good reasons for that design decision:

Ergonomy: Not all functionality and controls of a common native GUI application are also available as browser controls or require high programing efforts. For many browsers there's no complete keyboard support for all the controls, resulting in limitations of the ergonomy.
Security: A web interface to the server administration console can easily be abused, when the web server is miss-configured.
Compliance: A web based GUI application will require Javascript in order to realize enhanced functionality. This can lead to incompatibility with certain browsers or high programing efforts to prevent this.
Transactionality: A web based GUI requires a session mechanism and other programing efforts in order to implement the administration functionality in a transactional way, where the administrator can perform a couple of actions before he decides whether all changes shall be canceled or really be applied to the server configuration.

How can I be sure, that changes I made by hand in the configuration won't be overwritten when saving changes made with the administration application later?

See the answers to the next two questions.

What are these 'Generated' and 'Saved' sections in the configuration file?

The information stored in the configuration file by the Win32 administration application are separated into two major sections. The first section is completely written by the administration application, i.e. all manually edited entries are overwritten. This section is located between two specific comments in the configuration:

#+++---AD Generated Section, modifications will be lost---+++
#+++---AD Generated section end---+++

The second section won't be overwritten by the administration application, i.e. all manually edited entries are retained. This section is located between another two specific comments in the configuration:

#+++---AD Saved Section, modifications will be retained---+++
#+++---AD Saved section end---+++

You may add multiple Saved sections to your configuration file, even if the administration application will create only one as default. Do not move, copy or change the above comments or the contents between them without knowing the meaning of these sections!

How does the Win32 administration program store its proprietary information in the configuration file?

The third type of internal internal information stored as specific comments in the configuration file by the Win32 administration application are the configuration values, which have been set by the user in the GUI and have been used to write the configuration file. This information is read again, when the administration application starts.

#+++---AD Section Start, Do not Modify:Internal
#URLProtocol:https://
#DefaultPort:443
#ServerIOObjectLine: IOObject SSLIOObject
#DefaultMIMEType:application/octet-stream
#HandlerLine: Handlers Start Scripts WinScripts FastCGIScripts ISAPI Options Default
#MappingTypes:Documents
#MappingTypes:CGI
#MappingTypes:Windows CGI
#MappingTypes:Fast CGI
#MappingTypes:ISAPI
#MappingTypes:Redirect
#IOTypes:TCP
#IOTypes:SSL
#LoggingTypes:Access (CLF)
#LoggingTypes:Referer Logfile
#+++---AD Section End---+++

Besides the section Internal there are sections as General, HTTP, SSL and other. Some configuration tweaks are based on knowing, how these sections are processed by the administration application:

If you delete these sections, a configuration file cannot be edited with the administration application, i.e. a manually edited configuration cannot be overwritten anymore.
Most of these values are directly or indirectly used in the loaded configuration. You may change these values here if you edited them manually in the configuration in order to prevent them from beeing overwritten when the administration GUI is used the next time.
Some of the values in these internal sections are lookup values, as HandlerLine or are the members of a lookup list, as LoggingTypes. You may edit these values in order to extend the functionality of the administration application but this doesn't work for all values. This is especially usefull to add values to the Generated section of the configuration, where manually edited changes will normally be overwritten when saving changes made with the administration application, e.g. to edit the HandlerLine in order to add a user defined handler to the HttpLogicObject. The handler configuration itself can be added to the Saved section.

Can I change the realm for remote administration?

In the current release the administration creates a configuration file, where the remote administration belongs to the realm "Administration". This setting can only be changed manually.

Can I force SSL for remote administration?

Yes, the TopSiteRoot class has a new parameter 'ForceSSL'. It is available for Pi3Web 2.0.3 PL1 and allows only secure remote administration connections through SSL if enabled. Note, that the cipher strength is not checked in that case.

What makes the difference of the Pi3Web configuration format in comparison with XML?

The format of the configuration uses similar elements as XML, e.g. tags like <Object></Object>. But on the other hand, the format is flat, i.e. there's no document tree as in XML documents, but the structure is flat.

What can I do when I get an error during startup after the configuration has been changed?

Dependent on the startup type of the server (service - Pi3Srv32.exe, desktop application - EnhPi3.exe, command line desktop application - Pi3.exe) startup errors are printed out in either the location

service: file Pi3Web/bin/Pi3Error.log
desktop application: windows message dialog
command line application: stderr at the console

An example error message during startup is:

Errors:-
[../Conf/Config.pi3, line 202] MTMIOServer: Unknown parameter 'Bla'
In object starting at ../Conf/Config.pi3 173, 8
Failed to initialize object 'ThreadPoolDispatcher' of class 'MTMIOServerClass'.
Failed to initialize object 'Main' of class 'UNIXDaemonClass'.

This message provides information about the location (line,column) of the object description (body between <Object></Object> causing the error in the configuration file (173,8), the implementation class of the configuration object (MTMIOServer), the cause of the problem ('Unknown parameter') and the loaded configuration tree ('Main' - 'ThreadPoolDispatcher' - 'MTMIOServer'). This will help you to detect the error in the configuration file quickly.

How can I solve problems with the server configuation at runtime?

Switch on the debug log in order to find the handler causing the problem. With this information check the configuration file.

Do I need to write .pi3-files by hand?

No, you don't need but you may do this. When you run the Pi3Web server on Win32 platforms, you can use the administration application to perform almost all configuration tasks. But for Pi3Web on UNIX systems you currently need to perform this by hand. The remote administration client is the key for GUI based administration on UNIX systems in future releases.

Do I need to write .cnf-files by hand?

No. The configuration entry of a library is maintained with the source code of this library in a stub .cnf file. The configuration entry of each class within a library is concatenated to the .cnf file at compile time by a perl script (Source/Scripts/genconf.pl) once for each source file (this is done by evaluation of special sections in a source file by CNF_BEGIN - CNF_END).