PORTMASK ADMINISTRATOR MANUAL

The portmask license key is matched to the fully qualified host name and port number that is requested at the time of issue. The software may be re-installed at any time as long as these details match the license key.

service installation

• create a dns address record for the hostname that will be used

• ping the hostname to verify that it is correct

• logon to the server as an administrator

• open a command prompt console

• create a subdirectory for the portmask files

• navigate the command prompt to the subdirectory

• copy the portmask software archive file to the subdirectory

• unzip the portmask software archive file into the subdirectory

• open the portmask.ini file in a ascii text editor such as notepad.exe

• edit the auth=xxxx value and replace the xxxx with the license key

• edit the name=xxxx value and replace the xxxx with fully qualified domain name of the listening address

• edit the port=xxxx value and replace the xxxx with the listening port number

• edit the seed=xxxx value and replace the xxxx with the secret key word

• the [block] section of the portmask.ini file is used for both whitelisted and blacklisted ip addresses. enter each address in normal dotted decimal notation. since portmask will not act on requests arriving from these addresses, the list is effectively both a whitelist and blacklist. if the firewall rules would normally allow access by a specific address, portmask will not interfere with it. if the firewall rules would normally block access by a specific address, portmask will not open an aperture for it.

• save the portmask.ini file

• install the service by running the command:

  portmasks.exe /install portmask -ini {ini path}
  

  replacing {ini path} with the fully qualified path to the portmask.ini file.

• the portmask service is now installed for manual startup on the system account

• open the portmask.cmd file in a ascii text editor

• modify the commands that will permit and remove access to specific ip addresses. the command line passed to cmd.exe to control connections is of the form:

  portmask.cmd 192.168.0.20 1
  

  the last parameter is either 1 to start a session or 0 to close a session. therefore the parameter substitution at run time is:

  %1=address
  %2=state
  

  any valid commands may be used in the portmask.cmd batch file in addition to the example commands as replacements for the example commands

client installation

• Copy the client executable and the sample portmask.ini to the destination media.

• Edit the settings in portmask.ini to match the license key, server name and server port particular to your server.

• Save changes to portmask.ini

• If desired, create a start menu entry.

• pmclient.exe takes the arguments:

  {ini file path} {user name} {password|*}
  

  If * is used for the password parameter, the user will be prompted for their password. This is the recommended mode. However, the password parameter exists for unattended use such as scheduled backup jobs that need to use portmask to access the server.

adding and removing users

• To add users open a command console, navigate to the portmask directory and run the following command for each user to be added:

  pm-user {full path to portmask.ini file} username password
  

  This will write the required data to the portmask.ini file. Users should be given their password and not the cryptographic hash. The use of crytographic hashes prevents users with access to the portmask directory from learning other user passwords.

• To remove users, open the portmask.ini file in a ascii text editor, locate the line referencing the user, remove the line and save the file.

• Restart the portmask service to make the changes take effect.

finishing installation

• Change the portmask service startup mode from manual to automatic. This will ensure that the service is running and available every time the server is restarted. Remember to start the service if the service is not already running.

• Set the unexpected termination recovery action in all cases to restart service.

• Review the static firewall rules to ensure that they do not conflict with the expected behaviour. In general, the rules should only permit access to protected network ports by privileged hosts with static ip addresses that are in the [block] section of portmask.ini. All other access will be controlled through portmask responses.

managing portmask

• The windows service management console may be used to start and stop the portmask service.

• The portmask service can also be controlled at the command line using the commands:

  net start portmask
  net stop portmask
  

• If the portmask service is no longer required it can be disabled using the windows service management console.

• The portmask service can be removed using the command:

  portmask /remove portmask
  

  This removes all registry entries. The service will remain visible in the windows service manager until the server is restarted. The files can then be safely deleted.

monitoring portmask

• The windows service control manager will log system events whenever the portmask service is started or stopped.

• The portmask service logs all actions taken to the windows application event log under the source identifier of portmask.

• Current pending firewall aperture actions are in the file portmask.txt and portmask.tmp.

• The command output of portmask.cmd can be piped to a file of your choice.

emergency access

• If you do not have access to a computer with a portmask client available, just download the client here. Unzip it onto your borrowed computer, personalise the portmask.ini file and proceed normally. You may want to consider keeping a copy of the portmask client on a USB memory stick. This is completely safe as it does not alter the host computer in any way.

• If the user credentials have been accidentally or maliciously damaged on the server, it is still possible to use portmask. Substitute the secret passkey for both user name and password. This will allow a connection for an administrator to repair the damage. Since this bypasses the normal method, it is important that the passkey only be known by the administrator. It is not required for proper operation of the client, so it is not needed in the portmask.ini on client computers.