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 Mappings defined in B<AUTOSSL_TLS_PORT_MAP> take precedence over built-ins.
  56
  57 =head1 ENVIRONMENT
  58
  59 =over 4
  60
  61 =item AUTOSSL_BACKEND
  62
  63 which program to use as a upgrade-to-TLS helper.
  64 Supported: openssl (default), stunnel.
  65 Note, this is not B<AUTOSSL_TLS_CMD>.
  66 B<AUTOSSL_TLS_CMD> is set by autossl(1) internally.
  67
  68 =item AUTOSSL_CONVENIENCE
  69
  70 If set to "off" it does not try to guess SNI servername.
  71
  72 =item AUTOSSL_SILENT
  73
  74 Less diagnostical messages
  75
  76 =item AUTOSSL_UPGRADE_PORTS
  77
  78 Space-delimited list of port numbers which autossl should work on (default 80)
  79
  80 =item AUTOSSL_UPGRADE_IPS
  81
  82 Space-delimited list of IPs which autossl should work on.
  83 Unset to enable autossl on all IPs.
  84
  85 =item AUTOSSL_TLS_PORT_MAP
  86
  87 Space-delimited list of colon-separated port number pairs denoting which port should be mapped to which one.
  88 Some common ports are set by default (grep AUTOSSL_TLS_PORT_MAP to see which ones).
  89
  90 =item OPENSSL_EXTRA_ARGS
  91
  92 Additional options passed to openssl(1SSL) if it's used
  93
  94 =item STUNNEL_EXTRA_ARGS
  95
  96 Additional options passed to stunnel(8) if it's used
  97
  98 =back
  99
 100 =head1 RATIONALE
 101
 102 Provide encypted network communication support for softwares not speaking
 103 (high enough version of) SSL/TLS themself.
 104
 105 =head1 LIMITATIONS
 106
 107 May not work if I<COMMAND> connects to multiple services, because many
 108 SSL/TLS servers need to know which domain (website name) the client is
 109 about to connect to in order to present to right certificate for the
 110 domain. However autossl(1) knows only abount the IP address, not the
 111 domain name. This can be worked around, mostly in simple programms,
 112 communicating with just a few servers, by guessing the domain name from
 113 the command line arguments.
 114 This is done if AUTOSSL_CONVENIENCE is not off.
 115
 116 =head1 SEE ALSO
 117
 118 autossl.so(3)