letsencrypt_webfaction 1.1.4 → 1.1.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data.tar.gz.sig +0 -0
- data/README.md +93 -51
- data/letsencrypt_webfaction.gemspec +1 -1
- data/lib/letsencrypt_webfaction.rb +1 -1
- metadata +4 -4
- metadata.gz.sig +0 -0
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d2ea1d4c28df4ed1c40f8ff30f4ec651830dda82
|
|
4
|
+
data.tar.gz: 71e79aef3627aab021f4c4d420f079991e682157
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4b9f684f9a77b8c9b86cfe0da89f7b4375364feda37496c8c14ae53c965cd4f411359806b1572cb6a8ef8a99d95a3f7a924ac93a2aaddb752d1c20027e4187aa
|
|
7
|
+
data.tar.gz: 8fc7299c951347c35be2e5015edc58087baf44829a68fee98f4745c668df3c11d86dc9e40da0e1564593033696a2054578458e48c8130c28d814700385576072
|
checksums.yaml.gz.sig
CHANGED
|
Binary file
|
data.tar.gz.sig
CHANGED
|
Binary file
|
data/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# LetsEncrypt
|
|
1
|
+
# LetsEncrypt WebFaction
|
|
2
2
|
|
|
3
3
|
LetsEncrypt utility client for WebFaction hosts.
|
|
4
4
|
|
|
5
|
-
This tool simplifies the manual process of using LetsEncrypt on
|
|
5
|
+
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.
|
|
6
6
|
|
|
7
7
|
[](https://travis-ci.org/will-in-wi/letsencrypt-webfaction)
|
|
8
8
|
|
|
@@ -16,7 +16,7 @@ This tool simplifies the manual process of using LetsEncrypt on Webfaction hosts
|
|
|
16
16
|
|
|
17
17
|
[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.
|
|
18
18
|
|
|
19
|
-
LetsEncrypt
|
|
19
|
+
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.
|
|
20
20
|
|
|
21
21
|
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).
|
|
22
22
|
|
|
@@ -32,35 +32,40 @@ Cron is an application which will execute commands on a defined schedule. WebFac
|
|
|
32
32
|
|
|
33
33
|
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).
|
|
34
34
|
|
|
35
|
+
### SFTP
|
|
36
|
+
|
|
37
|
+
If you're not happy navigating around your server's folders and files through SSH, you might find some of this process easier if you access your server with an FTP client over Secure FTP. WebFaction [also has this covered](https://docs.webfaction.com/user-guide/access.html#connecting-with-ftp).
|
|
38
|
+
|
|
35
39
|
## Installation
|
|
36
40
|
|
|
37
41
|
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
|
|
38
42
|
|
|
39
|
-
All places where you need to substitute a value specific to your setup will be denoted with square brackets, e.g.
|
|
43
|
+
All places where you need to substitute a value specific to your setup will be denoted with square brackets, e.g. [yourdomain.com]. There are cases where shell variables are used, such as `$HOME`. These should be typed verbatim.
|
|
40
44
|
|
|
41
|
-
You can install LetsEncrypt
|
|
45
|
+
You can install LetsEncrypt WebFaction using the system Ruby or using RBEnv.
|
|
42
46
|
|
|
43
47
|
### System Ruby
|
|
44
48
|
|
|
45
49
|
This is the simpler method and is preferred.
|
|
46
50
|
|
|
47
|
-
Run the following command to install the letsencrypt_webfaction package via the [RubyGems package management site](https://rubygems.org/gems/letsencrypt_webfaction):
|
|
51
|
+
Run the following command in an SSH session to install the letsencrypt_webfaction package via the [RubyGems package management site](https://rubygems.org/gems/letsencrypt_webfaction):
|
|
48
52
|
|
|
49
53
|
```sh
|
|
50
54
|
GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib gem2.2 install letsencrypt_webfaction
|
|
51
55
|
```
|
|
52
56
|
|
|
53
|
-
Add the following to `~/.bash_profile`
|
|
57
|
+
Add the following to `~/.bash_profile` (using, for example, an FTP client or your favorite text editor):
|
|
54
58
|
|
|
55
59
|
```sh
|
|
56
60
|
function letsencrypt_webfaction {
|
|
57
61
|
PATH=$PATH:$GEM_HOME/bin GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib ruby2.2 $HOME/.letsencrypt_webfaction/gems/bin/letsencrypt_webfaction $*
|
|
58
62
|
}
|
|
59
63
|
```
|
|
64
|
+
This will simplify the running of the LetsEncrypt WebFaction command, by setting some variables in advance.
|
|
60
65
|
|
|
61
|
-
|
|
66
|
+
After saving `~/.bash_profile`, run the command `source $HOME/.bash_profile` to apply the new settings.
|
|
62
67
|
|
|
63
|
-
Now, you
|
|
68
|
+
Now, you are ready to run `letsencrypt_webfaction` from your SSH session to get certificates. See below for usage.
|
|
64
69
|
|
|
65
70
|
### RBEnv
|
|
66
71
|
|
|
@@ -76,86 +81,125 @@ Once you have done so, install Ruby 2.1+ (probably 2.3.0 at time of writing). Th
|
|
|
76
81
|
$ rbenv rehash # Makes RBenv aware of the letsencrypt_webfaction utility.
|
|
77
82
|
$ rm .ruby-version # Unsets Ruby 2.3.0 as the default version in the current folder.
|
|
78
83
|
|
|
79
|
-
##
|
|
84
|
+
## Usage
|
|
80
85
|
|
|
81
|
-
|
|
86
|
+
### Syntax
|
|
82
87
|
|
|
83
|
-
|
|
88
|
+
The syntax of the letsencrypt_webfaction command is as follows:
|
|
84
89
|
|
|
85
|
-
|
|
90
|
+
$ letsencrypt_webfaction --account_email <email-address> --domains <domain[,domain[,domain...]]> --public <server-folder>
|
|
86
91
|
|
|
87
|
-
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.
|
|
88
92
|
|
|
89
|
-
|
|
93
|
+
### Options:
|
|
90
94
|
|
|
91
|
-
|
|
95
|
+
The basic parameters are as follows:
|
|
92
96
|
|
|
93
|
-
|
|
94
|
-
# For system Ruby:
|
|
95
|
-
GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib gem2.2 install letsencrypt_webfaction
|
|
97
|
+
* `--account_email`
|
|
96
98
|
|
|
97
|
-
|
|
98
|
-
RBENV_VERSION=2.3.0 gem install letsencrypt_webfaction
|
|
99
|
-
```
|
|
99
|
+
Your WebFaction contact email address.
|
|
100
100
|
|
|
101
|
-
|
|
101
|
+
* `--domains`
|
|
102
|
+
|
|
103
|
+
The domains for which you want to create certificates, separated by commas (with no spaces). The domains must be served from the same folder. There is one certificate per webapp, regardless of how many domains are served from it.
|
|
102
104
|
|
|
103
|
-
|
|
105
|
+
* `--public`
|
|
104
106
|
|
|
105
|
-
|
|
107
|
+
A folder which is directly served at `http://[yourdomain.com]/` into which the ACME verification files can be placed.
|
|
106
108
|
|
|
107
|
-
|
|
109
|
+
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/[yourapp/]`.
|
|
108
110
|
|
|
109
|
-
|
|
111
|
+
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/[yourapp]/current/public/`.
|
|
110
112
|
|
|
111
|
-
|
|
113
|
+
In some cases (such as with some Node.js or Python applications), you may need to create this folder. See [here](https://github.com/will-in-wi/letsencrypt-webfaction/issues/24) for an example of this workaround.
|
|
114
|
+
|
|
115
|
+
If you have several webapps, then you will need to issue the command several times. The command can be run from any folder.
|
|
116
|
+
|
|
117
|
+
Other parameters (which are generally best left to their default values, unless you have a perticular need to change them) can be found in the `config.defaults.yml` configuration file (see below in the "More detailed examples" section).
|
|
118
|
+
|
|
119
|
+
### Example
|
|
120
|
+
Here is a basic example which issues one certificate for both yourdomain.com and www.yourdomain.com, both of which are served by `~/webapps/yourapp/wordpress` and your WebFaction contact email address is you@youremail.com. This assumes that both yourdomain.com and www.yourdomain.com are served from the same folder.
|
|
121
|
+
|
|
122
|
+
$ letsencrypt_webfaction --account_email you@youremail.com --domains yourdomain.com,www.yourdomain.com --public ~/webapps/yourapp/wordpress/
|
|
123
|
+
|
|
124
|
+
### Testing
|
|
125
|
+
|
|
126
|
+
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 rate limit of 5 certs per domain every 7 days. You can add the `--endpoint https://acme-staging.api.letsencrypt.org/` parameter to the `letsencrypt_webfaction` command to do so.
|
|
127
|
+
|
|
128
|
+
When testing, you will also want to change the `--support_email` parameter, so that an email is not sent needlessly to WebFaction Support. To do this, add `--support_email ""` (so no support email is sent) or `--support_email you@youremail.com` (so the support email is sent to you).
|
|
129
|
+
|
|
130
|
+
A test command could thus be something like the following:
|
|
112
131
|
|
|
113
|
-
|
|
132
|
+
$ letsencrypt_webfaction --account_email you@youremail.com --domains yourdomain.com,www.yourdomain.com --public ~/webapps/yourapp/wordpress/ --endpoint https://acme-staging.api.letsencrypt.org/ --support_email you@youremail.com
|
|
114
133
|
|
|
115
|
-
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]/`.
|
|
116
134
|
|
|
117
|
-
|
|
135
|
+
### Operation
|
|
118
136
|
|
|
119
|
-
|
|
137
|
+
When letsencrypt_webfaction runs, it places verification files into the public directory specified, validates the domains with LetsEncrypt, 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]/`.
|
|
120
138
|
|
|
121
|
-
|
|
139
|
+
After this is done, the utility will email the certificate installation request to WebFaction Support, copying you.
|
|
122
140
|
|
|
123
|
-
|
|
141
|
+
To quickly get a list of parameters and help for each, you can run:
|
|
124
142
|
|
|
125
|
-
|
|
143
|
+
$ letsencrypt_webfaction --help
|
|
126
144
|
|
|
127
|
-
|
|
145
|
+
Once you have the certificate installed and working, you will probably want to redirect the HTTP version of your site 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).
|
|
128
146
|
|
|
129
147
|
### Cron usage
|
|
130
148
|
|
|
131
149
|
Normally, you will run the script manually once to get the certificate, and then you will use Cron to automate future certificate renewal.
|
|
132
150
|
|
|
133
|
-
Your
|
|
151
|
+
Your Cron task could look something like:
|
|
134
152
|
|
|
135
153
|
# System Ruby Installation
|
|
136
|
-
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@
|
|
154
|
+
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@youremail.com] --domains [yourdomain.com,www.yourdomain.com] --public ~/webapps/[yourapp/your_public_html]/
|
|
137
155
|
# RBEnv Installation
|
|
138
|
-
0 4 1 */2 * RBENV_ROOT=~/.rbenv RBENV_VERSION=2.3.0 ~/.rbenv/bin/rbenv exec letsencrypt_webfaction --account_email [you@
|
|
156
|
+
0 4 1 */2 * RBENV_ROOT=~/.rbenv RBENV_VERSION=2.3.0 ~/.rbenv/bin/rbenv exec letsencrypt_webfaction --account_email [you@youremail.com] --domains [yourdomain.com,www.yourdomain.com] --public ~/webapps/[yourapp/your_public_html]/
|
|
157
|
+
|
|
158
|
+
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 (for example, you may want to run the task every two months initially, to be sure that everything is working before extending the period). Change the date of the Cron task so that WebFaction staff don't simultaneously receive all certificate change requests on the first day of the month.
|
|
159
|
+
|
|
160
|
+
If you have more than one Cron task running like this, you may want to set the environment variables at the top of the file, and create a config file containing the contact information.
|
|
161
|
+
|
|
162
|
+
If you want to be notified upon failure, you can add `MAILTO=[you@youremail.com]` to the top of the crontab. This will send you an email whenever any cron job outputs standard out or standard error, which is generally good practice.
|
|
163
|
+
|
|
164
|
+
## Upgrading
|
|
139
165
|
|
|
140
|
-
|
|
166
|
+
While WebFaction staff maintain your standard server software, the support team will not upgrade your installation of LetsEncrypt WebFaction. You won't usually need to do this unless you have an issue but, as is good practice with most software, it's best kept up to date.
|
|
141
167
|
|
|
142
|
-
|
|
168
|
+
You can find the current 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.
|
|
143
169
|
|
|
144
|
-
|
|
170
|
+
[The changelog](./CHANGELOG.md) describes changes from version to version.
|
|
145
171
|
|
|
146
|
-
|
|
172
|
+
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.
|
|
147
173
|
|
|
148
|
-
|
|
174
|
+
TL;DR: Be careful with major version upgrades and you should be fine with upgrading to minor or patch releases.
|
|
149
175
|
|
|
150
|
-
|
|
176
|
+
To upgrade, run one of the following two commands to fetch and install the newest version from RubyGems:
|
|
151
177
|
|
|
152
|
-
|
|
178
|
+
```sh
|
|
179
|
+
# For system Ruby:
|
|
180
|
+
GEM_HOME=$HOME/.letsencrypt_webfaction/gems RUBYLIB=$GEM_HOME/lib gem2.2 install letsencrypt_webfaction
|
|
181
|
+
|
|
182
|
+
# For RBenv
|
|
183
|
+
RBENV_VERSION=2.3.0 gem install letsencrypt_webfaction
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### More detailed examples
|
|
187
|
+
|
|
188
|
+
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 both a config file and command-line arguments are passed, they will be interleaved, with the command-line arguments having precedence.
|
|
189
|
+
|
|
190
|
+
A config file needs to be in [YAML format](http://www.yaml.org/refcard.html) 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.
|
|
191
|
+
|
|
192
|
+
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:
|
|
193
|
+
|
|
194
|
+
$ letsencrypt_webfaction --config [~/le_config.yml] --domains [yourdomain.com,www.yourdomain.com] --public ~/webapps/[yourapp/your_public_html/]
|
|
153
195
|
|
|
154
196
|
This could be run automatically every two months.
|
|
155
197
|
|
|
198
|
+
A config file can be placed anywhere in your WebFaction account. A good place might be `~/le_config/siteconfig.yml`.
|
|
199
|
+
|
|
156
200
|
### Custom email configuration
|
|
157
201
|
|
|
158
|
-
|
|
202
|
+
If you use a WebFaction email address, the process of sending emails to WebFaction Support should work just fine. In some cases, 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.
|
|
159
203
|
|
|
160
204
|
A Gmail example might be:
|
|
161
205
|
|
|
@@ -166,7 +210,7 @@ email_configuration:
|
|
|
166
210
|
:address: 'smtp.gmail.com'
|
|
167
211
|
:port: '587'
|
|
168
212
|
:enable_starttls_auto: true
|
|
169
|
-
:user_name: '[
|
|
213
|
+
:user_name: '[you@gmail.com]'
|
|
170
214
|
:password: '[password_see_note]'
|
|
171
215
|
:authentication: 'plain'
|
|
172
216
|
:domain: 'localhost.localdomain' # the HELO domain provided by the client to the server
|
|
@@ -184,9 +228,7 @@ To run the script directly from the repository, use:
|
|
|
184
228
|
|
|
185
229
|
$ ruby -Ilib exe/letsencrypt_webfaction
|
|
186
230
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
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.
|
|
231
|
+
See details in the "Testing" section above on how to use the Let's Encrypt stage server when developing, together with usage of the `--support_email` parameter in a testing environment.
|
|
190
232
|
|
|
191
233
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
192
234
|
|
|
@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
|
|
|
28
28
|
|
|
29
29
|
spec.required_ruby_version = '>= 2.1.0'
|
|
30
30
|
|
|
31
|
-
spec.add_runtime_dependency 'acme-client', '>=0.3.
|
|
31
|
+
spec.add_runtime_dependency 'acme-client', '>=0.3.7'
|
|
32
32
|
spec.add_runtime_dependency 'pony', '~> 1.11'
|
|
33
33
|
|
|
34
34
|
# Dependencies of dependencies when specific versions are needed.
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: letsencrypt_webfaction
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.1.
|
|
4
|
+
version: 1.1.5
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- William Johnston
|
|
@@ -30,7 +30,7 @@ cert_chain:
|
|
|
30
30
|
urnVFSXSvmjoq2UEqNf39Ffw4ZJ2QYuxlOLEInXhf1Rij1+KYHwHoT6qaOmk+fgY
|
|
31
31
|
XWr3WAp8Tv/ogSwGuBGWtsjMTEzbRxAJbRXQDFEMeXJAvzon0o6hUtU=
|
|
32
32
|
-----END CERTIFICATE-----
|
|
33
|
-
date: 2016-07-
|
|
33
|
+
date: 2016-07-30 00:00:00.000000000 Z
|
|
34
34
|
dependencies:
|
|
35
35
|
- !ruby/object:Gem::Dependency
|
|
36
36
|
name: acme-client
|
|
@@ -38,14 +38,14 @@ dependencies:
|
|
|
38
38
|
requirements:
|
|
39
39
|
- - ">="
|
|
40
40
|
- !ruby/object:Gem::Version
|
|
41
|
-
version: 0.3.
|
|
41
|
+
version: 0.3.7
|
|
42
42
|
type: :runtime
|
|
43
43
|
prerelease: false
|
|
44
44
|
version_requirements: !ruby/object:Gem::Requirement
|
|
45
45
|
requirements:
|
|
46
46
|
- - ">="
|
|
47
47
|
- !ruby/object:Gem::Version
|
|
48
|
-
version: 0.3.
|
|
48
|
+
version: 0.3.7
|
|
49
49
|
- !ruby/object:Gem::Dependency
|
|
50
50
|
name: pony
|
|
51
51
|
requirement: !ruby/object:Gem::Requirement
|
metadata.gz.sig
CHANGED
|
Binary file
|