Configure Your Linux System for use with Pagekite

By Jon Spriggs 2022-12-04, 11:16

• Configuring an HTTP back-end
• Configuring an SSH back-end
• Configuring PageKite as a public facing front-end
• Troubleshooting

Configuring an HTTP back-end

What is this? This is what you would do if you have a web-server, for example Apache or Nginx, running on your computer and you would like it to always be visible to the world whenever you have a working Internet connection.

Instructions

This assumes you have downloaded and installed the package as per DebianPackage or RpmPackage and have an account at pagekite.net:

1. Edit /etc/pagekite.d/10_account.rc:
   1. Replace "NAME.pagekite.me" with the name of one of your pagekites
   2. Replace "YOURSECRET" with the shared secret value from pagekite.net/home/
   3. Remove the line "abort_not_configured" and the comment above it.
2. Rename /etc/pagekite.d/80_httpd.rc.sample to /etc/pagekite.d/80_httpd.rc
3. If your web server is not listening on port 80, edit 80_httpd.rc and replace the port number in the service_on= (or backend=) line with the correct value. You can also add more back-ends, for example an https back-end if your web server is configured for native SSL.

4. Restart PageKite with one of the following commands:

   # RedHat/Fedora:
   service pagekite restart
   
   # Ubuntu/Debian:
   sudo invoke-rc.d pagekite restart
   

See below for some hints about how to test and debug your configuration if you have any problems.

---

Configuring an SSH back-end

Configuring an SSH back-end is almost exactly the same procedure as configuring an HTTP back-end, described above - the only difference is in step 2, when you should rename the /etc/pagekite.d/80_sshd.rc.sample to 80_sshd.rc.

Note that you will need to reconfigure your SSH clients as well, as described on the SshOverPageKite page.

---

Configuring PageKite as a public facing front-end

What is this? A PageKite front-end is useful if you have a server on the Internet and would like to use it instead of (or in addition to) the commercial pagekite.net service. Most people do not need this.

Instructions

This assumes you have downloaded and installed the package as per DebianPackage or RpmPackage.

1. Remove all the lines in /etc/pagekite.d/10_account.rc (but leave the file there!)

2. Edit /etc/pagekite.d/20_frontend.rc adding the following lines:

     isfrontend
     ports=80,443
     protos=http,https
     domain=http,https:*.your.domain:MakeUpAPasswordHere
   

3. Optional: If you are sharing your HTTP port between your pagekite instance and another web server, you can specify the IP address to bind to in /etc/pagekite.d/20_frontend.rc, as follows:

     host=192.168.0.1
   

   Then, create /etc/pagekite.d/80_backend.rc with the following:

     service_on=http:192.168.0.1:127.0.0.1:80:
     service_on=https:192.168.0.1:127.0.0.1:443:
     service_on=http:yourhostname:127.0.0.1:80:
     service_on=https:yourhostname:127.0.0.1:443:
     service_on=http:yourhostname,fqdn:127.0.0.1:80:
     service_on=https:yourhostname,fqdn:127.0.0.1:443:
   

   (alternately, use service_on=http:unknown:127.0.0.1:80)

   The above assume you're sharing your apache server by binding it to 127.0.0.1:80 and 127.0.0.1:443 and that your primary interface IP is 192.168.0.1.

4. Optional: If you wish to provide SSL/TLS encryption between the front-end and back-end, you will first need to generate SSL certificates.

     openssl req -new -x509 -keyout /etc/pagekite.d/site-key.pem \
       -out /etc/pagekite.d/site-cert.pem -days 365 -nodes
     cat /etc/pagekite.d/site-key.pem /etc/pagekite.d/site-cert.pem \
       |tee /etc/pagekite.d/frontend.pem
   

   You can examine the contents of the .pem files by using commands like these:

     cat /etc/pagekite.d/site-cert.pem | openssl x509 -text
     cat /etc/pagekite.d/frontend.pem | openssl x509 -text
   

   Once you've got your certificates, add this to /etc/pagekite.d/20_frontend.rc on the backend:

     frontend=frontend.your.domain:443
     fe_certname=frontend.your/domain
     ca_certs=/etc/pagekite.d/site-cert.pem
   

   Your front-ends need to have a copy of the frontend.pem file and include this line in their own configuration scripts:

     tls_endpoint=frontend.your.domain:/path/to/frontend.pem
   

---

Troubleshooting

System logs

The system-wide PageKite from the .deb and .rpm packages is configured to log details about what it is doing to the file /var/log/pagekite/pagekite.log.

That is generally the first place to look for information about what the program is doing (or not doing).

Interactive testing

If either of the above configurations do not seem to be working, it may be useful to stop the service (service pagekite stop or invoke-rc.d pagekite stop) and then experiment with the following command:

$ sudo pagekite --clean --optdir=/etc/pagekite.d

This will run PageKite interactively on the console, using the configuration from /etc/pagekite.d. This makes it easier to catch any configuration errors and test different settings.

Adding the arguments --logfile=stdio and --debugio may also be helpful in particularly difficult cases.