preload/autossl/autossl.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 autossl - Upgrade plain network socket to encrypted one with the help of autossl.so(3)
   7
   8 =head1 SYNOPSIS
   9
  10 autossl <COMMAND> [<ARGS>]
  11
  12 =head1 DESCRIPTION
  13
  14 Helper script to wrap any (dynamically linked) I<COMMAND> around and set up environment for
  15 autossl.so(3).
  16 LD_PRELOAD-able library autossl.so(3) intercepts connect(2) network
  17 connections and upgrade them to TLS.
  18
  19 This helper script helps you use autossl.so(3) and type less when using
  20 it with common simple commands, like C<wget URL>.
  21
  22 You probably use it only with simple commands anyways, which makes about
  23 1 or 2 connections needed to be upgraded by autossl, or only connects
  24 to IPs with no virtual domains (virtual domains are common at web
  25 servers).
  26 See LIMITATIONS below.
  27
  28 As part of the convenience functions, it
  29
  30 =over 4
  31
  32 =item 1
  33
  34 replaces https URL-looking command line argument to http, letting
  35 autossl.so(3) intercept the plain connection and upgrade it back to
  36 https during the connection.
  37
  38 =item 2
  39
  40 finds domain names in command line arguments and passes appropriate
  41 C<-servername> parameter to the underlaying openssl(1SSL) command.
  42
  43 =back
  44
  45 Turn these convenience functions off by setting
  46 C<AUTOSSL_CONVENIENCE=off> in your invoking environment.
  47
  48 May set B<OPENSSL_EXTRA_ARGS> environment to pass more parameters to
  49 openssl(1SSL).
  50
  51 autossl(1) has built-in port mapping which contains I<PLAIN>:I<TLS> port
  52 pairs for common protocols, but you can extend it by setting
  53 space-delimited I<PLAIN>:I<TLS> port number pairs in
  54 B<AUTOSSL_TLS_PORT_MAP> environment variable.
  55
  56 =head1 ENVIRONMENT
  57
  58 =over 4
  59
  60 =item AUTOSSL_BACKEND
  61
  62 which program to use as a upgrade-to-TLS helper.
  63 Supported: openssl (default), stunnel.
  64 Note, this is not B<AUTOSSL_TLS_CMD>.
  65 B<AUTOSSL_TLS_CMD> is set by autossl(1) internally.
  66
  67 =item AUTOSSL_CONVENIENCE
  68
  69 If set to "off" it does not try to guess SNI servername.
  70
  71 =item AUTOSSL_SILENT
  72
  73 Less diagnostical messages
  74
  75 =item AUTOSSL_UPGRADE_PORTS
  76
  77 Space-delimited list of port numbers which autossl should work on (default 80)
  78
  79 =item AUTOSSL_UPGRADE_IPS
  80
  81 Space-delimited list of IPs which autossl should work on.
  82 Unset to enable autossl on all IPs.
  83
  84 =item AUTOSSL_TLS_PORT_MAP
  85
  86 Space-delimited list of colon-separated port number pairs denoting which port should be mapped to which one.
  87 Some common ports are set by default (grep AUTOSSL_TLS_PORT_MAP to see which ones).
  88
  89 =item OPENSSL_EXTRA_ARGS
  90
  91 Additional options passed to openssl(1SSL) if it's used
  92
  93 =item STUNNEL_EXTRA_ARGS
  94
  95 Additional options passed to stunnel(8) if it's used
  96
  97 =back
  98
  99 =head1 RATIONALE
 100
 101 Provide encypted network communication support for softwares not speaking
 102 (high enough version of) SSL/TLS themself.
 103
 104 =head1 LIMITATIONS
 105
 106 May not work if I<COMMAND> connects to multiple services, because many
 107 SSL/TLS servers need to know which domain (website name) the client is
 108 about to connect to in order to present to right certificate for the
 109 domain. However autossl(1) knows only abount the IP address, not the
 110 domain name. This can be worked around, mostly in simple programms,
 111 communicating with just a few servers, by guessing the domain name from
 112 the command line arguments.
 113 This is done if AUTOSSL_CONVENIENCE is not off.
 114
 115 =head1 SEE ALSO
 116
 117 autossl.so(3)