Internet Control service setup

Before setting up the Internet Control service, verify that the Enable Internet Control Module option is enabled in the Options tab.

After the Internet proxy is setup and logging usernames correctly, then the PaperCut NG Internet Control service must be configured to monitor the proxy log files. The Internet Control service is a PaperCut NG program that is responsible for analyzing log files and reporting the usage back to the PaperCut NG Application Server. Once installed, the Internet Control service must be configured with the following settings:

Once these settings are configured, PaperCut NG can find the most recent log file, parse the contents and send usage information to the application server.

Where you install the PaperCut NG Internet Control service will depend on the layout of your network. Many networks will have a dedicated proxy server, which may or may not be a suitable candidate for a PaperCut NG application server installation. For this reason, the Internet Control service may either be deployed separately to the primary server, or access the proxy server logs remotely via a network share. Some reasons for separate deployment may include:

The following are some common network layout examples involving the Internet Control service. Check which option suits your network configuration, and follow the suggested setup instructions.

Single/primary server installation

This section described how to install the Internet Control service on the primary PaperCut NG application server as outlined in the section called “Internet Control service setup”. Follow the installation instructions for your server platform:

Windows single/primary server installation

  1. The setup wizard for the Internet Control service is included with the PaperCut NG application server. To start it, as an administrator level user run: StartProgram FilesPaperCut NGInternet ControlInternet Control Configuration Wizard, or the file located at [app-path]\providers\net\bin\win\setup-net-service.exe

  2. Select the type of proxy server you have under Web proxy type, and the location of your log files under Log file path. The Log mask will be set for automatically based on the selected proxy type. If you have changed the naming format of your log files, enter a custom file mask here.

    Selecting the proxy server type and log file location

    Figure 15.5. Selecting the proxy server type and log file location

  3. Press Test settings. The Test results area should now show some data reflecting the information found in the proxy log files. If the data looks correct (i.e. you recognize the user names and the data received looks correct), press Next. Otherwise, check that the information entered is correct, and that the log file path contains the correct log files.

    Example output from a test parse of proxy server log files

    Figure 15.6. Example output from a test parse of proxy server log files

    A few parse errors may be encountered if a log file has been corrupted in some way, but if there are too many this may indicate an incorrect log format. Check that the Web proxy type you have selected is correct for your system.

  4. Select an appropriate Security group for users with internet access. The Internet Control service will modify group membership to reflect the users who have available credit (i.e. when users run out of credit, they will be removed from this group). If you have not already created a group for this purpose when configuring your proxy server, it is recommended to create a new group with a name such as Internet Users.

    Selecting a security group to allow internet access

    Figure 15.7. Selecting a security group to allow internet access

    Tip

    By default, PaperCut NG adds users that have available credit to the selected security group. Depending on how your other proxy access rules are defined, it is sometimes more convenient to use a "Deny Group" that only contains the users without Internet access. To do this follow the instructions in the section called “Using a deny group for Internet access control”, after the wizard is complete.

    Once an appropriate group is selected, press Next.

  5. To allow the Internet Control service to modify group membership it must have the appropriate privileges. It is recommended to create a new domain user with appropriate privileges for this purpose. The password for the service account should be set to not expire.

    Selecting a service account

    Figure 15.8. Selecting a service account

    Press Next to continue.

  6. The Internet Control service will now be configured. Press Finish to complete the setup wizard.

    To confirm that the installation was successful and that the PaperCut NG application server is now monitoring internet usage, continue reading at the section called “Verifying the Net Control service setup”.

Using a deny group for Internet access control

By default, PaperCut NG adds users that have available credit to the selected security group. Depending on how your other proxy access rules are defined, it is sometimes more convenient to use a "Deny Group" that only contains the users without Internet access.

To reconfigure PaperCut NG to use a deny group:

  1. Stop the Internet Control service using Control Panel->Admin Tools->Services.

  2. Using a text editor, open the Internet Control config file: [app-path]\providers\net\config.properties.

  3. Change the security-group-is-deny-group entry in the config file to Y. i.e.:

        security-group-is-deny-group=Y
                                        

  4. Save the config file, and close the text editor.

  5. Restart the Internet Control service using Control Panel->Admin Tools->Services.

  6. Wait for a few minutes, and then check the contents of the selected security group. It should now only contain users that do not have credit available. NOTE: If you have many users it may take longer to complete the group updates.

Linux single/primary server installation

PaperCut NG includes a command-line utility to assist with this configuration. To perform this configuration:

  1. Log into the Linux server running PaperCut NG as the papercut user.

  2. Run the command: [app-path]/providers/net/bin/linux-[x64|i686]/setup-net-provider

  3. Follow the prompts, answering the questions as required.

  4. The utility will perform a test parse of the log file. Check that the results are as expected.

  5. When prompted, restart the Application server. This will restart the application server and the will also start the Internet Control service which will start parsing the log files.

  6. To confirm that the installation was successful and that the PaperCut NG application server is now monitoring internet usage, continue reading at the section called “Verifying the Net Control service setup”.

Mac single/primary server installation

PaperCut NG includes a command-line utility to assist with this configuration. To perform this configuration:

  1. Log into the Mac server running PaperCut NG.

  2. Start the service installation by double-clicking on the file:

    /Applications/PaperCut NG/providers/net/bin/mac/setup-net-provider.command

  3. Follow the prompts, answering the questions as required.

  4. The utility will perform a test parse of the log file. Check that the results are as expected.

  5. When prompted, restart the Application server. This will restart the application server and the will also start the Internet Control service which will start parsing the log files.

  6. To confirm that the installation was successful and that the PaperCut NG application server is now monitoring internet usage, continue reading at the section called “Verifying the Net Control service setup”.

Secondary server installation

This section described how to install the Internet Control service on the a secondary server that is separate to your primary PaperCut NG application server. The secondary server can run a different operating system to your primary server.

The process for installing the Internet Control service involves the following steps:

  1. Copying/installing the service files to the secondary server

  2. Running the setup process to install and configure the service

  3. Verify that the service is working correctly.

Prior to installing on a secondary server it is important to check the following:

  1. Ensure the primary server is set up correctly.

    Before installing the Internet Control service you should take some time to ensure the primary server (central application server) is set up and running correctly. If it is not running fine now adding an extra server will only "add an extra variable to the equation" and complicate troubleshooting. For example, verify that:

    • Users are allowed to login to user pages from their workstations.

    • Administrators can access the system.

  2. Ensure firewall software is set to allow access to port 9191.

    The Internet Control service needs to communicate (initiate a TCP connection) on port 9191 to the primary server. Administrators should ensure that any firewall software on the primary Application Server is not set to block any incoming local network traffic on this port. A quick way to check this is to ensure that you can access the administration pages from the secondary server using a web browser.

To complete the service installation, follow the instructions below for your secondary server platform:

Windows secondary server installation

  1. Install the Internet Control service

    Install the Internet Control service software onto the secondary server. On a Windows server, this is done by selecting the "Secondary Internet Server installation" option in the setup wizard.

  2. Configure the Internet Control service

    Continue with the steps found at the section called “Windows single/primary server installation”. In this setup wizard there is one additional step to configure the primary server connection details. The Internet Control service needs this so that it can connect to the primary server to report Internet usage.

  3. To confirm that the installation was successful and that the PaperCut NG application server is now monitoring internet usage, continue reading at the section called “Verifying the Net Control service setup”.

Linux secondary server installation

Step 1: Create the host user

The Internet Control service runs as the papercut user. This account must be created on the secondary server before proceeding. To create this user follow the steps described in the section called “Step 2 - Create the host user account and firewall settings”.

Confirm that the account is created successfully, by logging on to the system as the papercut user.

Step 2: Copy the service files to the secondary server

The instructions differ depending on the operating system running on the primary server. Select the instructions appropriate to your configuration.

If the primary server is running Linux then:

  1. Login to the primary server as the papercut user.

  2. Run the script: ~/providers/net/bin/linux-[x64|i686]/create-secondary-server-archive. This will create the file ~/net-secondary-server.tgz that contains all the files required on the secondary server.

  3. Copy the ~/net-secondary-server.tgz file to the secondary server, into the home directory of the papercut user.

  4. Login to the secondary server as papercut.

  5. Extract the files by running the following:

        shell> cd ~
        shell> tar xzf net-secondary-server.tgz
                                        

  6. Proceed to install and configure the service as described in the section called “Step 3: Install and configure the service”.

If the primary server is running Windows or Mac then:

  1. Log on the the primary application server.

  2. Copy all the files in in the [app-path]/providers/net/ directory, into the home directory of the papercut user on the secondary server. i.e. ~papercut/providers/net/. Make sure that all the files are owned by the papercut user.

  3. Login to the secondary server as the papercut user.

  4. On the secondary server, ensure that Sun Java 5.0 (or later) is installed. You can check the version installed by running java -version. This is available from http://java.sun.com.

  5. Change the permissions on ~papercut/providers/net/bin/linux-[x64|i686]/setup-net-provider to make it executable.

  6. Proceed to install and configure the service as described in the section called “Step 3: Install and configure the service”.

Step 3: Install and configure the service

To install and configure the service:

  1. Log on to the secondary server as the papercut user.

  2. Start the service setup process by running the following:

        shell> ./providers/net/bin/linux-[x64|i686]/setup-net-provider
                                        

  3. Follow the prompts, answering the questions as required.

  4. The program will perform a test parse of the log file. Check that the results are as expected.

  5. Once completed, confirm that the installation was successful and that the PaperCut NG application server is now monitoring internet usage, continue reading at the section called “Verifying the Net Control service setup”.

Mac secondary server installation

Step 1: Copy the service files to the secondary server

The instructions differ depending on the operating system running on the primary server. Select the instructions appropriate to your configuration.

If the primary server is running on Mac then:

  1. Login to the primary server.

  2. Double click the file: /Applications/PaperCut NG/providers/net/bin/mac/create-secondary-server-archive.command. This will create the file net-secondary-server.tgz in your home directory. It contains all the files required to run the Internet service on the secondary server.

  3. On the secondary server, create a directory for the application. e.g. /Applications/PaperCut NG

  4. Copy the file net-secondary-server.tgz file from the primary to the /Applications/PaperCut NG directory on the secondary server.

  5. On the secondary server open the Terminal application (e.g. a command prompt).

  6. Extract the files by entering the following in the Terminal application:

        $ cd "/Applications/PaperCut NG"
        $ tar xzf net-secondary-server.tgz
                                        

  7. Proceed to install and configure the service as described in the section called “Step 2: Install and configure the service”.

If the primary server is running Windows or Linux then:

  1. On the secondary server, create a directory for the application. e.g. /Applications/PaperCut NG

  2. Log on the the primary application server.

  3. Copy all the files in in the [app-path]/providers/net/ directory, into the /Applications/PaperCut NG on the secondary server.

  4. On the secondary server, change the permissions on /Applications/PaperCut NG/providers/net/bin/mac/setup-net-provider.command to make it executable.

  5. Proceed to install and configure the service as described in the section called “Step 2: Install and configure the service”.

Step 2: Install and configure the service

To install and configure the service:

  1. The secondary server requires that Java version 5.0 or higher is installed. If Java 5 is not already installed, the installer is available from the Apple website at: http://www.apple.com/support/downloads/java2se50release3.html.

  2. On the secondary server, start the setup process by double-clicking on the file /Application/PaperCut NG/providers/net/bin/mac/setup-net-provider.command

  3. Follow the prompts, answering the questions as required.

  4. The program will perform a test parse of the log file. Check that the results are as expected.

  5. Once completed, confirm that the installation was successful and that the PaperCut NG application server is now monitoring internet usage, continue reading at the section called “Verifying the Net Control service setup”.

Verifying the Net Control service setup

First verify that the Net Control service is running. To do this:

  1. Login to the admin pages of PaperCut NG

  2. Navigate to the Internet section.

  3. Look at the bottom of the page in the Internet Control Service Status section. This show the last status message from the service and the time the status was last updated.

  4. If the status text is The Internet Control service has never been started, then the service has not started properly. If this is the case, recheck the settings as described above and try restarting the application server and internet services as required. See Figure 15.9, “Example of Internet Control service status when service is running.”.

    If the service is not running, then the log files can be useful in diagnosing problems. The log file location depends on the platform and whether the Internet Control service is running on the primary server or a separate secondary server.

    • Primary server (Windows) - [app-path]\providers\net\logs\net-provider.log

    • Primary server (Linux/Mac) - [app-path]/server/logs/server.log

    • Secondary server (Windows) - [app-path]\providers\net\logs\net-provider.log

    • Secondary server (Linux/Mac) - [app-path]/providers/net/logs/net-provider.log

    Example of Internet Control service status when service is running.

    Figure 15.9. Example of Internet Control service status when service is running.

  5. If the service is running correctly then access the Internet using the proxy server and verify that the status indicates that the service is reading the logs. This should be apparent because the current line number should be increasing, and the status update time will update.

  6. By default the service reports Internet usage to the Application server once a minute. Once this time has elapsed the Internet Usage Log can be viewed and should include the recent internet usage. If this is the case then the Internet Charging service is correctly monitoring the proxy logs.