Commit 20af9b03 authored by Aral Balkan's avatar Aral Balkan
Browse files

Improve readme

  - Improve examples
  - Move note on privileged ports to end
parent 1d971df0
......@@ -34,93 +34,43 @@ Works on Linux, macOS, and Windows (WSL is not supported for certificates at loc
npm i @small-tech/https
```
## A note on Linux and the security farce that is “privileged ports”
Linux has an outdated feature dating from the mainframe days that requires a process that wants to bind to ports < 1024 to have elevated privileges. While this was a security feature in the days of dumb terminals, today it is a security anti-feature. (macOS has dropped this requirement as of macOS Mojave.)
## Examples
On modern Linux systems, you can disable privileged ports like this:
### At localhost with automatically-provisioned development certificates via mkcert.
```sh
sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0
```
```js
import https from '@small-tech/https'
Or, if you want to cling to ancient historic relics like a conservative to a racist statue, ensure your Node process has the right to bind to so-called “privileged” ports by issuing the following command before use:
const server = https.createServer((request, response) => {
response.end('Hello, world!')
})
```sh
sudo setcap cap_net_bind_service=+ep $(which node)
server.listen(443, () => {
console.log(' 🎉 Server running at https://localhost.')
})
```
If you are wrapping your Node app into an executable binary using a module like [Nexe](https://github.com/nexe/nexe), you will have to ensure that every build of your app has that capability set. For an example of how we do this in [Site.js](https://sitejs.org), [see this listing](https://source.ind.ie/site.js/app/blob/master/bin/lib/ensure.js#L124).
## Example
Here’s a basic Express “hello, world” app that shows you how this module can be used. Note that you don’t need express to use it.
1. ### Set up:
```sh
# Create the project folder and switch to it.
mkdir example && cd example
# Create a new npm module for the example.
npm init --yes
# Install dependencies.
npm i @small-tech/https express
# Open up the main file in your default editor.
$EDITOR index.js
```
2. ### Code (index.js):
```javascript
const https = require('..')
// Helpers
function html(message) {
return `<!doctype html><html lang='en'><head><meta charset='utf-8'/><title>Hello, world!</title><style>body{background-color: white; font-family: sans-serif;}</style></head><body><h1>${message}</h1></body></html>`
}
const contentTypeHTML = {'Content-Type': 'text/html'}
let options = {}
// For globally-trusted Let’s Encrypt certificates uncomment the following section.
// To provision certificates, also remove “staging: true” property.
// const os = require('os')
// options = {
// domains: [os.hostname()],
// staging: true
// }
Hit `https://localhost` and you should see your site with locally-trusted TLS certificates.
// Create HTTPS server at https://localhost
// with locally-trusted certificates.
const server = https.createServer(options, (request, response) => {
if (request.method !== 'GET') {
response.writeHead(404, contentTypeHTML)
response.end(html('Not found.'))
return
}
// Respond to all routes with the same page.
response.writeHead(200, contentTypeHTML)
response.end(html('Hello, world!'))
})
### At hostname with automatically-provisioned Let’s Encrypt certificates.
server.listen(443, () => {
console.log(' 🎉 Server running on port 443.')
})
```
```js
import https from '@small-tech/https'
import os form 'os'
3. ### Run:
const hostname = os.hostname()
const options = { domains: [hostname] }
```sh
node index
```
const server = https.createServer((request, response) => {
response.end('Hello, world!')
})
Hit `https://localhost` and you should see your site with locally-trusted TLS certificates.
server.listen(443, () => {
console.log(` 🎉 Server running at https://${hostname}.`)
})
```
To provision globally-trusted Let’s Encrypt certificates instead, uncomment the `options` object and pass it as the first argument in the `createServer()` method.
To provision globally-trusted Let’s Encrypt certificates, we additionally create an `options` object containing the domain(s) we want to support, and pass it as the first argument in the `createServer()` method.
You can find a version of this example in the `/example` folder. To download and run that version:
......@@ -138,6 +88,24 @@ npm i
npm run example
```
## A note on Linux and the security farce that is “privileged ports”
Linux has an outdated feature dating from the mainframe days that requires a process that wants to bind to ports < 1024 to have elevated privileges. While this was a security feature in the days of dumb terminals, today it is a security anti-feature. (macOS has dropped this requirement as of macOS Mojave.)
On modern Linux systems, you can disable privileged ports like this:
```sh
sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0
```
Or, if you want to cling to ancient historic relics like a conservative to a racist statue, ensure your Node process has the right to bind to so-called “privileged” ports by issuing the following command before use:
```sh
sudo setcap cap_net_bind_service=+ep $(which node)
```
If you are wrapping your Node app into an executable binary using a module like [Nexe](https://github.com/nexe/nexe), you will have to ensure that every build of your app has that capability set. For an example of how we do this in [Site.js](https://sitejs.org), [see this listing](https://source.ind.ie/site.js/app/blob/master/bin/lib/ensure.js#L124).
## Related projects
Lower-level:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment