letsencrypt_webfaction 1.1.3 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0dd3914e759095eb5e9668786c5faa3afd08d6e5
-  data.tar.gz: 36bf677f35925bc8c638aeb6f99149eca3842fd0
+  metadata.gz: 83c1b3f724a12f75203d4d279ca98398efb67623
+  data.tar.gz: c76364b7a81bf4e28e4db65d83fc993c1fc1cced
 SHA512:
-  metadata.gz: dbe3efb8443c182dbe1d9bf1a4a934f95340eb27df51f688bc353f7b10adb5e475ea54c920142cc612a7c7930516428ff9be927d38502033029ae7506737af89
-  data.tar.gz: a79fc55f6f3608bcf625f375986a28a64e173707fb05f160d3730273d9c215fe0b024e9afc54fe8a4c23f44a119228bcc889ae27e05052b5a44715fc9ca08fad
+  metadata.gz: 1e2befa31cdd2e53cbb6dfb50dd1cfa17263a4add4a48f2b397707e876b881631db94bc57d3f1f41b67d91bfa8bc475de88091c229c5721390c8341e41dc477e
+  data.tar.gz: c4d3cf0bdd1bc6bef919cc8811988e2000f722e5c0eb6942c8dc88e1d07b251e61b79d986fd4618a1e3e82a4ad70ab3728990f4cde386b82146b32d7cb5a5b3b

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+v1.1.4
+
+* Show version number with `--version` flag.
+
 v1.1.3
 
 * Lock version of activesupport so that older versions of Ruby still work.

data/README.md

@@ -2,7 +2,7 @@
 
 LetsEncrypt utility client for WebFaction hosts.
 
-This tool simplifies the manual process of using LetsEncrypt on Webfaction hosts. It can be added to cron where it will validate your domains automatically, place the generated certificates in a common folder, and then email the Webfaction support team to request installation, also notifying you.
+This tool simplifies the manual process of using LetsEncrypt on Webfaction hosts. It can be added to the Cron scheduled task runner where it will validate your domains automatically, place the generated certificates in a common folder, and then email the Webfaction support team to request installation, also notifying you.
 
 [![Build Status](https://travis-ci.org/will-in-wi/letsencrypt-webfaction.svg?branch=master)](https://travis-ci.org/will-in-wi/letsencrypt-webfaction)
 
@@ -12,23 +12,45 @@ This tool simplifies the manual process of using LetsEncrypt on Webfaction hosts
 
 *Note: if you find this useful and are setting up a new account, you can support me a little by using [my WebFaction affiliate link](https://www.webfaction.com/?aid=49923). I think I get a 10% referal bonus from whatever you spend at WebFaction. Thanks!*
 
+## Why not Certbot?
+
+[Certbot](https://certbot.eff.org/) is the "official" (in that it was the first and to some extent reference client) Let's Encrypt client. Let's Encrypt decided to focus Certbot on a particular use case, namely the configuration of servers which are directly facing the internet and can have the Certbot application run as root. For other use cases, they encourage the implementation of other clients tailored to different cases. This has spawned a wide variety of alternative implementations.
+
+LetsEncrypt Webfaction is just such an alternative implementation. It was built because the WebFaction use case does not fit in the Certbot preconditions, namely that users don't have root access to change the frontend Nginx server configuration. WebFaction thus far requires that we place the certificate and private key somewhere on the server and then submit a ticket to install the certificate. This is exactly the workflow that is being automated.
+
+Certbot could probably be used in "manual" mode to create the certificate on disk, and then something else wired up to make the certificate installation request. For various reasons, I decided not to do this. If someone creates instructions to do this, I'd be happy to link to it from [the wiki](https://github.com/will-in-wi/letsencrypt-webfaction/wiki).
+
+## Prerequisite topics
+
+Below are a list of server administration topics that it is assumed you know in order to follow the installation and setup instructions. If you find something in the readme that is unclear to you, please open a ticket and I'll try to improve the documentation!
+
+### Cron
+
+Cron is an application which will execute commands on a defined schedule. WebFaction has [some good documentation on how to use it](https://docs.webfaction.com/software/general.html#scheduling-tasks-with-cron).
+
+### SSH
+
+All of the commands listed below (unless specified otherwise) are run in an SSH session on the server. Again, WebFaction has written a [splendid little tutorial on how to get this working](https://docs.webfaction.com/user-guide/access.html#ssh).
+
 ## Installation
 
 This utility works on [CentOS 6 and 7 boxes](https://docs.webfaction.com/user-guide/server.html#finding-your-server-s-operating-system). The CentOS 5 systems do not have a new enough OpenSSL to include the algorithms required. You may be able to make this work using rbenv and compiling openssl yourself. A tutorial for CentOS 5 is available here: https://github.com/will-in-wi/letsencrypt-webfaction/wiki/Install-custom-OpenSSL-and-Ruby-on-CentOS-5-host
 
+All places where you need to substitute a value specific to your setup will be denoted with square brackets, e.g. `[mydomain.tld]`. There are cases where shell variables are used, such as `$HOME`. These should be typed verbatim.
+
 You can install LetsEncrypt Webfaction using the system Ruby or using RBEnv.
 
 ### System Ruby
 
 This is the simpler method and is preferred.
 
-Run the following command to install:
+Run the following command to install the letsencrypt_webfaction package via the [RubyGems package management site](https://rubygems.org/gems/letsencrypt_webfaction):
 
 ```sh
 GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib gem2.2 install letsencrypt_webfaction
 ```
 
-Add the following to `~/.bash_profile`:
+Add the following to `~/.bash_profile` to simplify the running of LetsEncrypt Webfaction with a bash function:
 
 ```sh
 function letsencrypt_webfaction {
@@ -36,34 +58,74 @@ function letsencrypt_webfaction {
 }
 ```
 
-Then run `source $HOME/.bash_profile`.
+Then run the command `source $HOME/.bash_profile` to apply the new settings.
 
-Now, you can run `letsencrypt_webfaction` from the shell.
+Now, you can run `letsencrypt_webfaction` from the shell to get certificates. You can run this from any folder.
 
 ### RBEnv
 
-This method is useful if you are already using RBEnv to manage Ruby.
+This method is useful if you are already using RBEnv to manage Ruby, or if you are already a Ruby developer. If neither of these cases are true, just use the system Ruby method.
 
 Follow the instructions to [set up RBEnv](https://github.com/rbenv/rbenv) and [Ruby Build](https://github.com/rbenv/ruby-build#readme) on your WebFaction server.
 
 Once you have done so, install Ruby 2.1+ (probably 2.3.0 at time of writing). Then set the local Ruby and install the Gem. Finally unset the local Ruby so that you don't run into problems.
 
-    $ rbenv install 2.3.0
-    $ rbenv local 2.3.0
-    $ gem install letsencrypt_webfaction
-    $ rbenv rehash
-    $ rm .ruby-version
+    $ rbenv install 2.3.0 # Installs Ruby 2.3.0
+    $ rbenv local 2.3.0 # Sets Ruby 2.3.0 as the default version in the current folder.
+    $ gem install letsencrypt_webfaction # Installs this utility from RubyGems.
+    $ rbenv rehash # Makes RBenv aware of the letsencrypt_webfaction utility.
+    $ rm .ruby-version # Unsets Ruby 2.3.0 as the default version in the current folder.
+
+## Upgrading
+
+The WebFaction support team will not upgrade your installation of LetsEncrypt Webfaction. You don't usually need to do this unless you have an issue, but as a general rule with most software it is good to do occasionally.
+
+You can find the version by running `letsencrypt_webfaction --version`. Sort of. In versions >= 1.1.4, this will work. In older versions, this will just print `letsencrypt_webfaction: version unknown` due to an oversight on my part. So if you get the latter output, just upgrade.
+
+[The changelog](./CHANGELOG.md) describes changes from version to version.
+
+LetsEncrypt Webfaction follows [Semantic Versioning](http://semver.org/). In a nutshell, a version number such as `1.2.3` is divided as `major.minor.patch`. When the major version is incremented, you will probably have to change something about the configuration to make it work. The changelog will let you know what changes you need to make. When the minor version is incremented, there are new features but existing features haven't changed. If the patch version is incremented, the changes are all under the hood and shouldn't change or add any existing features.
+
+TL;DR: Be careful with major version upgrades and you should be fine with upgrading to minor or patch releases.
+
+To upgrade, run one of the following two commands to fetch and install the newest version from RubyGems:
+
+```sh
+# For system Ruby:
+GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib gem2.2 install letsencrypt_webfaction
+
+# For RBenv
+RBENV_VERSION=2.3.0 gem install letsencrypt_webfaction
+```
 
 ## Usage
 
-Basic example:
+Here is a basic example which issues one certificate for both example.com and www.example.com which is served by `~/webapps/myapp/my_public_html` when your WebFaction contact email address is myemail@example.com. This assumes that both example.com and www.example.com are served from the same folder. An easy way to think about it is that there is one certificate per webapp, regardless of how many domains are served from it.
 
-    $ letsencrypt_webfaction --account_email me@example.com --domains example.com,www.example.com --public ~/webapps/myapp/public_html/
+    $ letsencrypt_webfaction --account_email [myemail@example.com] --domains [example.com,www.example.com] --public ~/webapps/[myapp]/[my_public_html]/
 
-To quickly get a list of parameters, you can call:
+The certificate will be placed in `~/le_certs/example.com/[timestamp]/` and WebFaction will be emailed to install the certificate.
+
+To quickly get a list of parameters and help for each, you should run:
 
     $ letsencrypt_webfaction --help
 
+To test certificate issuance, consider using the [LetsEncrypt staging server](https://community.letsencrypt.org/t/testing-against-the-lets-encrypt-staging-environment/6763). This doesn't have the 5 certs per domain every 7 days rate limit. You can add the `--endpoint https://acme-staging.api.letsencrypt.org/` parameter to the `letsencrypt_webfaction` command to do so.
+
+When letsencrypt_webfaction runs, it places verification files into a public directory, validates the domains with LetsEncrypt (or your ACME provider), and then dumps the signed certificate and private key into an output folder. By default, the output folder is `~/le_certs/`, inside which it will create `[domain_name]/[timestamp]/`.
+
+After this is done, the utility will email the cert installation request to Webfaction support and also copy you.
+
+Once you have the certificate installed and working, you will probably want to redirect the HTTP version to the HTTPS version. WebFaction has [documentation describing how to do this](https://docs.webfaction.com/software/static.html#static-redirecting-from-http-to-https).
+
+### Public folders
+
+For this utility to work, it is assumed that there is a folder which is directly served at `http://[yourdomain]/` into which the ACME verification files can be placed.
+
+In the case of a PHP site, such as Drupal or Wordpress, look for the folder with `index.php` in it. This is usually in `/home/[myuser]/webapps/[myapp/]`.
+
+In the case of a Rails app, look for a folder called `public/`. If you are deploying your app with Capistrano, this could show up in `/home/myuser/webapps/[myapp]/current/public/`.
+
 ### Cron usage
 
 Normally, you will run the script manually once to get the certificate, and then you will use Cron to automate future certificate renewal.
@@ -71,9 +133,9 @@ Normally, you will run the script manually once to get the certificate, and then
 Your cron task could look something like:
 
     # System Ruby Installation
-    0 4 1 */2 *     PATH=$PATH:$GEM_HOME/bin GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib ruby2.2 $HOME/.letsencrypt_webfaction/gems/bin/letsencrypt_webfaction --account_email you@example.com --domains example.com,www.example.com --public ~/webapps/myapp/
+    0 4 1 */2 *     PATH=$PATH:$GEM_HOME/bin GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib ruby2.2 $HOME/.letsencrypt_webfaction/gems/bin/letsencrypt_webfaction --account_email [you@example.com] --domains [example.com,www.example.com] --public ~/webapps/[myapp]/
     # RBEnv Installation
-    0 4 1 */2 *     RBENV_ROOT=~/.rbenv RBENV_VERSION=2.3.0 ~/.rbenv/bin/rbenv exec letsencrypt_webfaction --account_email you@example.com --domains example.com,www.example.com --public ~/webapps/myapp/
+    0 4 1 */2 *     RBENV_ROOT=~/.rbenv RBENV_VERSION=2.3.0 ~/.rbenv/bin/rbenv exec letsencrypt_webfaction --account_email [you@example.com] --domains [example.com,www.example.com] --public ~/webapps/[myapp]/
 
 This [would run](http://crontab.guru/#0_4_1_*/2_*) at 4 a.m. on the first day of January, March, May, July, September, and November. Certificates expire three months after issuance, so modify as desired. It may be preferable to change the date of the month that your cron task runs on so that WebFaction staff don't simultaneously receive all certificate change requests at the same time.
 
@@ -83,33 +145,17 @@ If you have more than one cron task running like this, you may want to set the e
 
 Default parameters can be found in [config.defaults.yml](./config.defaults.yml). All of the parameters can be overridden by passing another config file, arguments to the executable, or both. If a config file and arguments are passed, they will be interleaved with the arguments having precedence.
 
-A config file needs to be in YAML format and have a subset of the keys in [config.defaults.yml](./config.defaults.yml). If you use a config file, you pass the `--config ./myconfig.yml` parameter.
+A config file needs to be in YAML format and have a subset of the keys in [config.defaults.yml](./config.defaults.yml). If you use a config file, you add the `--config [./myconfig.yml]` parameter to the letsencrypt_webfaction command.
 
 This allows you to set up a cron task for multiple sites with the defaults for all of them (such as your email address) in a config file, and site specific directives in the command. For example:
 
-    $ letsencrypt_webfaction --config ~/le_config.yml --domains example.com,www.example.com --public ~/webapps/myapp/public_html/
+    $ letsencrypt_webfaction --config [~/le_config.yml] --domains [example.com,www.example.com] --public ~/webapps/[myapp/public_html/]
 
 This could be run automatically every two months.
 
-### Operation
-
-When the code runs, it places verification files into a public directory, validates the domains with LetsEncrypt (or your ACME provider), and then dumps the signed certificate and private key into an output folder. By default, the output folder is `~/le_certs/`, inside which it will create `[domain_name]/[timestamp]/`.
-
-After this is done, the utility will email the cert installation request to Webfaction support and also copy you.
-
-If you see messages containing SyntaxErrors, you are most likely using an old version of Ruby. This utility requires Ruby 2.1+.
-
-### Public folders
-
-For this utility to work, it is assumed that there is a folder which is directly served at `http://yourdomain/` into which the ACME verification files can be placed.
-
-In the case of a PHP site, such as Drupal or Wordpress, look for the folder with `index.php` in it. This is usually in `/home/myuser/webapps/myapp/`.
-
-In the case of a Rails app, look for a folder called `public/`. If you are deploying your app with Capistrano, this could show up in `/home/myuser/webapps/myapp/current/public/`.
-
 ### Custom email configuration
 
-Particularly in the case of Gmail, you may need to override the default usage of Sendmail and use SMTP. You can add custom configuration to the config file you pass, in order to accomplish this.
+Particularly in the case of Gmail, you may need to override the default usage of Sendmail and use SMTP. You can create a custom configuration file as described above (passed using `--config`) and add the below custom configuration in order to accomplish this.
 
 A Gmail example might be:
 
@@ -120,23 +166,25 @@ email_configuration:
     :address: 'smtp.gmail.com'
     :port: '587'
     :enable_starttls_auto: true
-    :user_name: 'myuser@gmail.com'
-    :password: 'password_see_note'
+    :user_name: '[myuser@gmail.com]'
+    :password: '[password_see_note]'
     :authentication: 'plain'
     :domain: 'localhost.localdomain' # the HELO domain provided by the client to the server
 ```
 
-See the wiki for additional Gmail specific notes.
+See this [project's GitHub wiki](https://github.com/will-in-wi/letsencrypt-webfaction/wiki) for additional Gmail specific notes.
 
 For all possible options, see [the Pony configuration](https://github.com/benprew/pony).
 
 ## Development
 
+If you are interested in contributing to this project with new code or bugfixes, welcome!
+
 To run the script directly from the repository, use:
 
     $ ruby -Ilib exe/letsencrypt_webfaction
 
-To test certificate issuance, consider using the [LetsEncrypt staging server](https://community.letsencrypt.org/t/testing-against-the-lets-encrypt-staging-environment/6763). This doesn't have the 5 certs per domain every 7 days rate limit. You can add the `--endpoint https://acme-staging.api.letsencrypt.org/` parameter to do so.
+The note above about the Let's Encrypt stage server is very helpful when developing.
 
 You will probably also want to use the argument `--support_email ""` which will keep support from actually being contacted. Alternately, set the `support_email` address to be yourself.
 

data/lib/letsencrypt_webfaction.rb

@@ -1,3 +1,3 @@
 module LetsencryptWebfaction
-  VERSION = '1.1.3'.freeze
+  VERSION = '1.1.4'.freeze
 end

data/lib/letsencrypt_webfaction/args_parser.rb

@@ -1,6 +1,7 @@
 require 'optparse'
 require 'yaml'
 
+require 'letsencrypt_webfaction'
 require 'letsencrypt_webfaction/args_parser/field'
 require 'letsencrypt_webfaction/args_parser/string_validator'
 require 'letsencrypt_webfaction/args_parser/defined_values_validator'
@@ -41,7 +42,7 @@ module LetsencryptWebfaction
       file_path = File.join(File.dirname(__FILE__), '../../', DEFAULTS_PATH)
       load_config!(File.expand_path(file_path))
 
-      # TODO: Rework this to not exit on instantiation due to help text.
+      # TODO: Rework this to not exit on instantiation due to help text or version.
       parse!
     end
 
@@ -88,6 +89,13 @@ module LetsencryptWebfaction
       end
     end
 
+    def handle_version(opts)
+      opts.on_tail('--version', 'Show version') do
+        puts LetsencryptWebfaction::VERSION
+        exit
+      end
+    end
+
     def handle_field(opts, field)
       opts.on("--#{field.identifier}=#{field.identifier.upcase}", field.description) do |val|
         instance_variable_set("@#{field.identifier}", field.sanitize(val))
@@ -100,6 +108,7 @@ module LetsencryptWebfaction
 
         handle_config(opts)
         handle_help(opts)
+        handle_version(opts)
         FIELDS.each { |field| handle_field(opts, field) }
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsencrypt_webfaction
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.1.4
 platform: ruby
 authors:
 - William Johnston
@@ -30,7 +30,7 @@ cert_chain:
   urnVFSXSvmjoq2UEqNf39Ffw4ZJ2QYuxlOLEInXhf1Rij1+KYHwHoT6qaOmk+fgY
   XWr3WAp8Tv/ogSwGuBGWtsjMTEzbRxAJbRXQDFEMeXJAvzon0o6hUtU=
   -----END CERTIFICATE-----
-date: 2016-07-02 00:00:00.000000000 Z
+date: 2016-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acme-client