1PAGEKITE(1) Awesome Commands PAGEKITE(1)
2
6 pagekite v0.5.9.3 - Make localhost servers publicly visible
7
10 pagekite [--options] [service] kite-name [+flags]
11
14 PageKite is a system for exposing localhost servers to the public
15 Internet. It is most commonly used to make local web servers or SSH
16 servers publicly visible, although almost any TCP-based protocol can
17 work if the client knows how to use an HTTP proxy.
18 PageKite uses a combination of tunnels and reverse proxies to
20 compensate for the fact that localhost usually does not have a public
21 IP address and is often subject to adverse network conditions,
22 including aggressive firewalls and multiple layers of NAT.
23 This program implements both ends of the tunnel: the local "back-end"
25 and the remote "front-end" reverse-proxy relay. For convenience,
26 pagekite also includes a basic HTTP server for quickly exposing files
27 and directories to the World Wide Web for casual sharing and
28 collaboration.
29
32 Basic usage, gives http://localhost:80/ a public name:
33 $ pagekite NAME.pagekite.me
34 To expose specific folders, files or use alternate local ports:
36 $ pagekite /a/path/ NAME.pagekite.me +indexes # built-in HTTPD
37 $ pagekite *.html NAME.pagekite.me # built-in HTTPD
38 $ pagekite 3000 NAME.pagekite.me # HTTPD on 3000
39 To expose multiple local servers (SSH and HTTP):
41 $ pagekite ssh://NAME.pagekite.me AND 3000 NAME.pagekite.me
42
46 The most comman usage of pagekite is as a back-end, where it is used to
47 expose local services to the outside world.
48 Examples of services are: a local HTTP server, a local SSH server, a
50 folder or a file.
51 A service is exposed by describing it on the command line, along with
53 the desired public kite name. If a kite name is requested which does
54 not already exist in the configuration file and program is run
55 interactively, the user will be prompted and given the option of
56 signing up and/or creating a new kite using the pagekite.net service.
57 Multiple services and kites can be specified on a single command-line,
59 separated by the word 'AND' (note capital letters are required). This
60 may cause problems if you have many files and folders by that name, but
61 that should be relatively rare. :-)
62
65 The options --list, --add, --disable and --remove can be used to
66 manipulate the kites and service definitions in your configuration
67 file, if you prefer not to edit it by hand. Examples:
68 Adding new kites
71 $ pagekite --add /a/path/ NAME.pagekite.me +indexes
72 $ pagekite --add 80 OTHER-NAME.pagekite.me
73 To display the current configuration
75 $ pagekite --list
76 Disable or delete kites (--add re-enables)
78 $ pagekite --disable OTHER-NAME.pagekite.me
79 $ pagekite --remove NAME.pagekite.me
80
84 Flags are used to tune the behavior of a particular kite, for example
85 by enabling access controls or specific features of the built-in HTTP
86 server.
87 Common flags
90 +ip/1.2.3.4
91 Enable connections only from this IP address.
92 +ip/1.2.3
94 Enable connections only from this /24 netblock.
95 HTTP protocol flags
98 +password/name=pass
99 Require a username and password (HTTP Basic Authentication)
100 +rewritehost
103 Rewrite the incoming Host: header.
104 +rewritehost=N
106 Replace Host: header value with N.
107 +rawheaders
109 Do not rewrite (or add) any HTTP headers at all.
110 +insecure
112 Allow access to phpMyAdmin, /admin, etc. (per kite).
113 Built-in HTTPD flags
116 +indexes
117 Enable directory indexes.
118 +indexes=all
120 Enable directory indexes including hidden (dot-) files.
121 +hide Obfuscate URLs of shared files.
123 +cgi=list
126 A list of extensions, for which files should be treated as CGI
127 scripts (example: +cgi=cgi,pl,sh).
128
131 The full power of pagekite lies in the numerous options which can be
132 specified on the command line or in a configuration file (see below).
133 Note that many options, especially the service and domain definitions,
135 are additive and if given multiple options the program will attempt to
136 obey them all. Options are processed in order and if they are not
137 additive then the last option will override all preceding ones.
138 Although pagekite accepts a great many options, most of the time the
140 program defaults will Just Work.
141 Common options
144 --clean
145 Skip loading the default configuration file.
146 --signup
148 Interactively sign up for pagekite.net service.
149 --defaults
151 Set defaults for use with pagekite.net service.
152 --whitelabel=D
154 Set defaults for pagekite.net white-labels.
155 --whitelabels=D
157 Set defaults for pagekite.net white-labels (with TLS).
158 --nocrashreport
160 Don't send anonymous crash reports to pagekite.net.
161 Back-end options
164 --shell
165 Run PageKite in an interactive shell.
166 --nullui
168 Silent UI for scripting. Assumes Yes on all questions.
169 --list List all configured kites.
172 --add Add (or enable) the following kites, save config.
174 --remove
176 Remove the following kites, save config.
177 --disable
179 Disable the following kites, save config.
180 --only Disable all but the following kites, save config.
182 --insecure
185 Allow access to phpMyAdmin, /admin, etc. (global).
186 --local=ports
189 Configure for local serving only (no remote front-end).
190 --watch=N
192 Display proxied data (higher N = more verbosity).
193 --noproxy
196 Ignore system (or config file) proxy settings.
197 --proxy=type:server:port, --socksify=server:port, --torify=server:port
200 Connect to the front-ends using SSL, an HTTP proxy, a SOCKS
201 proxy, or the Tor anonymity network. The type can be any of
202 'ssl', 'http' or 'socks5'. The server name can either be a
203 plain hostname, user@hostname or user:password@hostname. For
204 SSL connections the user part may be a path to a client cert PEM
205 file. If multiple proxies are defined, they will be chained one
206 after another.
207 --service_on=proto:kitename:host:port:secret
210 Explicit configuration for a service kite. Generally kites are
211 created on the command-line using the service short-hand
212 described above, but this syntax is used in the config file.
213 --service_off=proto:kitename:host:port:secret
216 Same as --service_on, except disabled by default.
217 --service_cfg=..., --webpath=...
220 These options are used in the configuration file to store
221 service and flag settings (see above). These are both likely to
222 change in the near future, so please just pretend you didn't
223 notice them.
224 --frontend=host:port
227 Connect to the named front-end server. If this option is
228 repeated, multiple connections will be made.
229 --frontends=num:dns-name:port
232 Choose num front-ends from the A records of a DNS domain name,
233 using the given port number. Default behavior is to probe all
234 addresses and use the fastest one.
235 --nofrontend=ip:port
238 Never connect to the named front-end server. This can be used to
239 exclude some front-ends from auto-configuration.
240 --fe_certname=domain
243 Connect using SSL, accepting valid certs for this domain. If
244 this option is repeated, any of the named certificates will be
245 accepted, but the first will be preferred.
246 --fe_nocertcheck
249 Connect using SSL/TLS, but do not verify the remote certificate.
250 This is largely insecure but still thwarts passive attacks and
251 prevents routers and firewalls from corrupting the PageKite
252 tunnel.
253 --ca_certs=/path/to/file
256 Path to your trusted root SSL certificates file.
257 --dyndns=X
260 Register changes with DynDNS provider X. X can either be simply
261 the name of one of the 'built-in' providers, or a URL format
262 string for ad-hoc updating.
263 --keepalive=N
266 Force traffic over idle tunnels every N seconds, to cope with
267 firewalls that kill idle TCP connections. Backend only: if set
268 to "auto" (the default), the interval will be adjusted
269 automatically in response to disconnects.
270 --all Terminate early if any tunnels fail to register.
273 --new Don't attempt to connect to any kites' old front-ends.
275 --fingerpath=P
277 Path recipe for the httpfinger back-end proxy.
278 --noprobes
280 Reject all probes for service state.
281 Front-end options
284 --isfrontend
285 Enable front-end operation.
286 --domain=proto,proto2,pN:domain:secret
289 Accept tunneling requests for the named protocols and specified
290 domain, using the given secret. A * may be used as a wildcard
291 for subdomains or protocols.
292 --authdomain=auth-domain, --authdomain=target-domain:auth-domain
295 Use auth-domain as a remote authentication server for the
296 DNS-based authetication protocol. If no target-domain is given,
297 use this as the default authentication method.
298 --motd=/path/to/motd
301 Send the contents of this file to new back-ends as a "message of
302 the day".
303 --host=hostnameListen on the given hostname only.
306 --ports=list
308 Listen on a comma-separated list of ports.
309 --portalias=A:BReport port A as port B to backends (because firewalls).
311 --protos=list
313 Accept the listed protocols for tunneling.
314 --rawports=list
317 Listen for raw connections these ports. The string '%s' allows
318 arbitrary ports in HTTP CONNECT.
319 --accept_acl_file=/path/to/file
322 Consult an external access control file before accepting an
323 incoming connection. Quick'n'dirty for mitigating abuse. The
324 format is one rule per line: `rule policy comment` where a rule
325 is an IP or regexp and policy is 'allow' or 'deny'.
326 --client_acl=policy:regexp, --tunnel_acl=policy:regexp
329 Add a client connection or tunnel access control rule. Policies
330 should be 'allow' or 'deny', the regular expression should be
331 written to match IPv4 or IPv6 addresses. If defined, access
332 rules are checkd in order and if none matches, incoming
333 connections will be rejected.
334 --tls_default=name
337 Default name to use for SSL, if SNI (Server Name Indication) is
338 missing from incoming HTTPS connections.
339 --tls_endpoint=name:/path/to/file
342 Terminate SSL/TLS for a name using key/cert from a file.
343 System options
346 --optfile=/path/to/file
347 Read settings from file X. Default is ~/.pagekite.rc.
348 --optdir=/path/to/directory
351 Read settings from /path/to/directory/*.rc, in lexicographical
352 order.
353 --savefile=/path/to/file
356 Saved settings will be written to this file.
357 --save Save the current configuration to the savefile.
360 --settings
363 Dump the current settings to STDOUT, formatted as a
364 configuration file would be.
365 --nozchunks
368 Disable zlib tunnel compression.
369 --sslzlib
371 Enable zlib compression in OpenSSL.
372 --buffers=N
374 Buffer at most N kB of data before blocking.
375 --logfile=F
377 Log to file F, stdio means standard output.
378 --daemonize
380 Run as a daemon.
381 --runas=U:G
383 Set UID:GID after opening our listening sockets.
384 --pidfile=P
386 Write PID to the named file.
387 --errorurl=U
389 URL to redirect to when back-ends are not found.
390 --errorurl=D:UCustom error URL for domain D.
392 --selfsign
395 Configure the built-in HTTP daemon for HTTPS, first generating a
397 new self-signed certificate using openssl if necessary.
398 --httpd=X:P, --httppass=X, --pemfile=X
401 Configure the built-in HTTP daemon. These options are likely to
402 change in the near future, please pretend you didn't see them.
403
406 If you are using pagekite as a command-line utility, it will load its
407 configuration from a file in your home directory. The file is named
408 .pagekite.rc on Unix systems (including Mac OS X), or pagekite.cfg on
409 Windows.
410 If you are using pagekite as a system-daemon which starts up when your
412 computer boots, it is generally configured to load settings from
413 /etc/pagekite.d/*.rc (in lexicographical order).
414 In both cases, the configuration files contain one or more of the same
416 options as are used on the command line, with the difference that at
417 most one option may be present on each line, and the parser is more
418 tolerant of white-space. The leading '--' may also be omitted for
419 readability and blank lines and lines beginning with '#' are treated as
420 comments.
421 NOTE: When using -o, --optfile or --optdir on the command line, it is
423 advisable to use --clean to suppress the default configuration.
424
427 Please keep in mind, that whenever exposing a server to the public
428 Internet, it is important to think about security. Hacked webservers
429 are frequently abused as part of virus, spam or phishing campaigns and
430 in some cases security breaches can compromise the entire operating
431 system.
432 Some advice:
434 * Switch PageKite off when not using it.
436 * Use the built-in access controls and SSL encryption.
437 * Leave the firewall enabled unless you have good reason not to.
438 * Make sure you use good passwords everywhere.
439 * Static content is very hard to hack!
440 * Always, always make frequent backups of any important work.
441 Note that as of version 0.5, pagekite includes a very basic request
444 firewall, which attempts to prevent access to phpMyAdmin and other
445 sensitive systems. If it gets in your way, the +insecure flag or
446 --insecure option can be used to turn it off.
447 For more, please visit: <https://pagekite.net/support/security/>
449
452 Using pagekite as a front-end relay with the native Python SSL module
453 may result in poor performance. Please use the pyOpenSSL wrappers
454 instead.
455
458 lapcat(1), <http://pagekite.org/>, <https://pagekite.net/>
459
462 - Bjarni R. Einarsson <http://bre.klaki.net/>
463 - The Beanstalks Project ehf. <https://pagekite.net/company/>
464 - The Rannis Technology Development Fund <http://www.rannis.is/>
465 - Joar Wandborg <http://wandborg.se/>
466 - Luc-Pierre Terral
468
471 Copyright 2010-2017, the Beanstalks Project ehf. and Bjarni R.
472 Einarsson.
473 This program is free software: you can redistribute it and/or modify it
475 under the terms of the GNU Affero General Public License as published
476 by the Free Software Foundation, either version 3 of the License, or
477 (at your option) any later version.
478 This program is distributed in the hope that it will be useful, but
480 WITHOUT ANY WARRANTY; without even the implied warranty of
481 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
482 General Public License for more details.
483 You should have received a copy of the GNU Affero General Public
485 License along with this program. If not, see:
486 <http://www.gnu.org/licenses/>
487https://pagekite.net/ 2018-01-24 PAGEKITE(1)