Michiel Appelman

Setting up a Matrix Server with Cloudflare

Tue, 18 Apr 2023 23:03:00 +0200

Matrix is an open source project and standard for instant-messaging. It’s already being used (in an adapted form, mostly) by government agencies and corporations in some parts of the world. In the past it had been a bit tedious to set up, so over the past two years or so, I’ve payed Element to host a Matrix server for me. However, since I have not been using it much but was also missing some flexibility to play with the server itself, I started looking at self-hosting again.

Luckily, there has been some very active development on automating those deployments on Github: spantaleev/matrix-docker-ansible-deploy. And since the Matrix protocol itself is HTTPS-based, most of the services can actually be exposed through Cloudflare. This adds some useful security and by using Cloudflare Tunnels we can also host this anywhere: there are no dependencies on static IP addresses or poking holes in your firewall.

In this guide I’ll show you how to:

Connect to your server with SSH through Cloudflare Tunnel
Configure Ansible and the Matrix Docker playbooks to get your first deployment going
Exposing the Matrix services through Cloudflare Tunnel
Setting up proper delegation and discovery with Cloudflare Workers
Using Cloudflare R2 for media storage
How to receive Cloudflare webhook notifications in your new Matrix server

Note

If you haven’t noticed yet: yes, I’m very biased to using Cloudflare here. Although I work there as a Solutions Engineer, I do pay for my own Pro account and do these things for fun.

Server Setup

As we want to focus on the Matrix + Cloudflare part, I’ll not spend to much time on getting the server set up, but any major distro should work, and easiest is to use one that’s supported on the pkg.cloudflare.com list so you can grab cloudflared from the package repository.

To connect to your server through Cloudflare Tunnel, you’ll basically need to follow this tutorial: Connect to SSH server with cloudflared access. You’ll create a Public Hostname such as this:

Public Hostname for SSH on your server

I’m also skipping a big part about getting Access Applications set up for this, BTW. So if you haven’t already, please take some time to go through:

Setting up user authentication, either through a One-time PIN or an Identity Provider (Recommended).
Protecting hostnames using authentication with Cloudflare Access Applications.

When you feel ready with that setup, you’ll need to install cloudflared on your own computer (from where you normally run SSH) as well (for macOS users: brew install cloudflared). By using the ProxyCommand in .ssh/config, you’ll be able to transparently connect to the server:

Host ssh.example.com
    ProxyCommand /usr/local/bin/cloudflared access ssh --hostname %h

Test whether that works and if you did have any ports open on your firewall for SSH towards your server, feel free to close them. All your SSH traffic will now be going over the Cloudflare Tunnel. Isn’t that a safe feeling!?

Connecting with Ansible

First start by having a read through the matrix-docker-ansible-deploy docs. Specifically:

Because we’ve configured our server to be reachable through Cloudflare Tunnel, we need to make some advanced adjustments to the inventory/hosts file:

[matrix_servers]
matrix.example.com ansible_host=ssh.example.com

[matrix_servers:vars]
ansible_ssh_user=root
ansible_ssh_private_key_file='~/.ssh/id_ed25519'
ansible_ssh_common_args='-o ProxyCommand="/opt/homebrew/bin/cloudflared access ssh --hostname %h" '

This looks pretty similar to the .ssh/config set up, and I also included the SSH key that the connection should use, which I also assume is something you’ve set up for your server.

When this looks good you can test the connection to the server with Ansible by running the following command:

ansible -i inventory/hosts all -m ping -v

Configuring the Playbook

Most of the customization is already done by now. What’s left is putting Cloudflare Tunnel in front of the two main Matrix services, and deploying the full set of services.

Since we’ll use Cloudflare Tunnel as the main point of entry, we’ll follow the matrix-docker-ansible-deploy docs about using your own webserver. If we follow along in that article, you’ll end up with a configuration file looking like this:

# By default, the playbook manages its own Traefik (https://doc.traefik.io/traefik/) reverse-proxy server.
# It will retrieve SSL certificates for you on-demand and forward requests to all other components.
# For alternatives, see `docs/configuring-playbook-own-webserver.md`.
matrix_playbook_reverse_proxy_type: playbook-managed-traefik

# Ensure that public urls use https
matrix_playbook_ssl_enabled: true

# Disable the web-secure (port 443) endpoint, which also disables SSL certificate retrieval
devture_traefik_config_entrypoint_web_secure_enabled: false
devture_traefik_container_web_host_bind_port: "127.0.0.1:81"
devture_traefik_config_entrypoint_web_forwardedHeaders_insecure: true
devture_traefik_additional_entrypoints_auto:
  - name: matrix-federation
    port: 8449
    host_bind_port: "127.0.0.1:8449"
    config: {}

# Disable integrated Coturn server
matrix_coturn_enabled: false

I disabled the TURN service because I have no need for audio/video calls through Matrix. Enabling TURN is possible, but then you’d have to expose your server from outside of Cloudflare, which might be a bit scary.

With all of the base configuration done, have a look at the installation instructions (or blindly run just setup-all 😅).

Cloudflare Tunnel

While that is doing its thing (without any errors 🤞), we can proceed to expose the services through Cloudflare Tunnel. What’s important to note is that a single service on the server has to have a single hostname. This means we cannot expose the Matrix Client service (exposed locally behind port 81) and the Matrix Server service (local port 8449) both behind matrix.example.com. However, we’ll trick the Matrix server into thinking that it is running on the same hostname.

For that we create two Public Hostnames:

matrix.example.com pointing to port 81 on the server:

Public Hostname for Matrix where clients connect to
matrix-fed.example.com pointing to port 8449 with Host header set to matrix.example.com:

Public Hostname for Matrix where othere servers connect to for federation

Now when a server connects to the matrix-fed.example.com hostname, our Matrix server will think that everything is fine and being served a matrix.example.com, because we’ve overriden the Host header in the Cloudflare Tunnel.

Delegation and Discovery

But how will other servers know to connect to matrix-fed.example.com, and not matrix.example.com? Well, for that we’ll use the delegation and discovery mechanisms build in to the Matrix specification.

To do proper delegation, you must use the ‘well-known’ files at the root of your domain (example.com), not an SRV record. This is because we use a delegated server and the Matrix Specification says that:

DNS is insecure (not all domains have DNSSEC), so the target of the delegation must prove that it is a valid delegate for <hostname> via TLS.

If you already have an easy way to serve files on your main domain, you need to provide the following two files:

Available under the https://example.com/.well-known/matrix/client URI:

{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  },
  "m.identity_server": {
    "base_url": "https://vector.im"
  }
}

And vailable under the https://example.com/.well-known/matrix/server URI:

{ "m.server": "matrix-fed.example.com:8443" }

If you have nothing on your main domain, you can also create a directory structure matrix-well-known/.well-known/matrix containing these two files and uploading them to Cloudfare Pages with example.com as a custom domain.

Workers

A more advanced use case, is where you already have some application running on your main (apex) domain, and can’t easily add these static files there. If that application is being proxied through Cloudflare, you can leverage Workers with custom routes (aka triggers) to dynamically reply to these requests.

Because the simple nature of such a Worker, I created it through the dashboard and assigned the following route triggers to it:

Worker Triggers, aka Routes for .well-known Matrix files

This also allows me to get the same results on all my domains, without having to manually keep them in sync.

I then used the “Quick Edit” function to compose the following quick-and-dirty script:

const HOMESERVER_URL = "https://matrix.example.com";
const IDENTITY_SERVER_URL = "https://vector.im";
const FEDERATION_SERVER = "matrix-fed.example.com:8443";

export default {
  async fetch(request, env) {
    const path = new URL(request.url).pathname;
    switch (path) {
      case "/.well-known/matrix/client":
        return new Response(
          `{"m.homeserver": {"base_url": "${HOMESERVER_URL}"},"m.identity_server": {"base_url": "${IDENTITY_SERVER_URL}"}}`
        );
      case "/.well-known/matrix/server":
        return new Response(`{"m.server": "${FEDERATION_SERVER}"}`);
      default:
        return new Response("Invalid request");
    }
  },
};

Simple enough! And it does the job without interfering with the rest of my websites.

Congratulations! You now should have a fully functional Matrix server! To celebrate, feel free to send me a message on Matrix.

Also take a look at enabling sending emails through a relay server. I used the service provided by my VPS hoster TransIP. This is especially useful to verify email addresses associated to your Matrix identity.

Finish setting up your server and make sure you update the services every once in a while according to the docs!

Tip

Please continue reading if you want to learn about setting up R2 and Webhook notifications in Cloudflare, but note that these are paid features.

R2 for Media Storage

Another fun thing I tried is to use Cloudflare’s S3-compatible storage called R2 as a media store. This is very easy to setup with matrix-docker-ansible-deploy as well, by following the instructions in the docs but adapting to R2:

matrix_synapse_ext_synapse_s3_storage_provider_enabled: true
matrix_synapse_ext_synapse_s3_storage_provider_config_bucket: matrix-media
matrix_synapse_ext_synapse_s3_storage_provider_config_region_name: auto
matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://xxxxxxxxxxx.r2.cloudflarestorage.com
matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: xxxxxxxxxxx
matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: xxxxxxxxxxx

Note the region is set to auto, but the other variables should be self explanatory if you follow the R2 documenation and create an Edit API token.

Webhook Notifications

If you are a paying Cloudflare customer, you’re able to configure webhook notifications in your dashboard. I desperately wanted to use this feature, so my next step was to get them delivered in my new Matrix server. For this, we’ll need to enable the ‘generic’ webhooks in the Hookshot bridge:

matrix_hookshot_enabled: true
matrix_hookshot_generic_enabled: true

For more info on setting this up, see the matrix-docker-ansible-deploy docs for hookshot.

After you rerun the deploy command (just setup-all) your Matrix server should be back up. Open your Element client, invite the bot in to a room where you want to receive the notifications, and make sure to give it Mod powers. Then send it a message containing !hookshot webhook Cloudflare to the room. If everything went well, you should now receive a private message from the Hookshot bot containing a URL that you can then use in the Cloudflare dashboard.

Deleting a Webhook

One thing I ran into was that there is no easy way to delete a webhook once created. For that you need Hookshot’s provisioning API. Opening up the host_vars YAML file again to add it:

matrix_hookshot_provisioning_enabled: true
matrix_hookshot_provisioning_port: 9002 # default port
matrix_hookshot_provisioning_secret: "XXXXXX"
matrix_hookshot_provisioning_internal: "/v1"
matrix_hookshot_provisioning_endpoint: "https://hookshot.example.com{{ matrix_hookshot_provisioning_internal }}"

matrix_hookshot_container_http_host_bind_ports:
  - "127.0.0.1:9002:9002"

Then run the setup again with just setup-all. While that runs, go to the Cloudflare Zero Trust dashboard, and add a Public Hostname to the Cloudflare Tunnel, and remember to also protect it with an Access Application.

Public Hostname for the Hookshot provisioning API

When all that’s done, you’ll be able to run curl commands using cloudflared providing your Matrix user identity in the query and the provisioning secret in the Authorization header:

cloudflared access curl "https://hookshot.example.com/v1/$ROOM_ID/connections?userId=%40user%3Aexample.com" -H "Authorization: Bearer $PROV_SECRET"

Running an IPv6-only webserver

Fri, 29 Jul 2022 17:00:00 +0200

Recently more and more hosters have started to offer IPv6-only virtual private servers (VPSs) that give you your own dedicated server at a major discount:

TransIP - SandboxVPS – €2,50/month (ex. VAT)
v6Node.com – €9/year - recently featured on Hacker News
Hetzner – disable IPv4 for a server and start from €3,62/month
PCextreme – €1,00/month
Possibly a lot more, see for some examples the HN thread linked above.

If you have not been blessed with IPv6 connectivity at home, that might look pretty useless. How do you connect to the server to manage it with SSH? How do you actually connect to the web application you want to host? Luckily there is a way around this by using Cloudflare Tunnel and SSH Access.

Choosing the right server

The easiest way to get Cloudflare Tunnel installed is by using a distribution and version for which Cloudflare releases pre-built packages of Cloudflare Tunnel (aka cloudflared). An up-to-date complete list can be found on the package repository.

You can also pick any other distribution and take care of the installation of the cloudflared executable yourself as described on the GitHub page: cloudflare/cloudflared.

Note

The next steps assume you have a Cloudflare Free account with a domain onboarded, and have done the initial setup of your Zero Trust dashboard.

Cloudflare Tunnel

Open the Cloudflare Zero Trust dashboard, navigate to Access > Tunnels and click Create New Tunnel.

You can pick a name and will then get to the following screen where you can copy paste the command to install the cloudflared package based on your OS:

Connecting the connector

The bottom part of the screen will auto-refresh to show you any connectors that have been found to connect to Cloudflare, but this probably won’t happen yet.

To get the connector to connect to Cloudflare using IPv6-only, we need to change the way the service is started. For this change the systemd unit file located at /etc/systemd/system/cloudflared.service to include the --edge-ip-version 6 option in the ExecStart command. It should look something like this:

[Unit]
Description=cloudflared
After=network.target

[Service]
TimeoutStartSec=0
Type=notify
ExecStart=/usr/bin/cloudflared --edge-ip-version 6 --no-autoupdate tunnel run --token xxxxx
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Restart the service and you should be seeing a connection pop up in the Cloudflare Zero Trust dashboard. Click Next.

Add an SSH Service

On the next screen you will configure a Public Hostname for the SSH server that’s running on the server. Simply choose a hostname as part of your Cloudflare domain and point it to SSH on the localhost:

Set a public hostname for the SSH application

That’s it! Finish the configuration for the Tunnel by clicking Save.

Note

Another cool thing about Cloudflare Tunnel is that it will setup an outbound connection to the Cloudflare Edge. This means you will not have to open any ports towards your IPv6-only server with your provider! Not for SSH, nor for HTTP(S) traffic.

Protect the SSH Application

Now head over to the Access > Applications screen to add a new ‘Self-hosted’ application for your vps-ssh.example.com public hostname:

Setup an Access Application to protect the SSH service

In the Identity providers section you can always choose One-time PIN or get Okta onboarded first (did you know they have a free Developer sign-up?). This will take care of the authentication of the users.

Next you will have to define the authorization for the application. For example, you want to limit access only to certain email addresses or members of specific Okta groups:

Configure an authentication policy

And finally on the next screen you can scroll down and enable browser-rendering for the SSH session so that you can connect without any terminal.

Enable browser rendering

Connect from a terminal

Connecting through a browser can be nice a last-resort, but most times an actual terminal is much more comfortable. Based on the Cloudflare docs we can now try to connect to the just configured SSH application through a terminal.

First install cloudflared on your local machine, eg. with brew:

brew install cloudflare/cloudflare/cloudflared

Second, edit your ~/.ssh/config file to include a Host for your new VPS SSH application with a special proxy command:

Host vps
  Hostname vps-ssh.example.com
  ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h

Also be sure to include the right IdentityFiles that your VPS expecting, and you should be good to go! Running ssh vps should now open a browser window where you should be able to authenticate and then be redirected back to your terminal.

With all of that setup, you now have your own webserver available through Cloudflare, reachable over IPv4 and IPv6, but just connected to IPv6. When you’re ready to add your first web applications, go back into the Access > Tunnels > VPS Tunnel configuration and add a new Public Hostname that points to the port on localhost where the application is running. Have fun!

Create a new public hostname for the HTTP application

Ditching QWERTY

Wed, 16 Feb 2022 10:00:00 +0100

I’m not sure what typing level you were when you started your career. Still, I think it is safe to say that I was not at a level that prepared me for working life primarily spent at a keyboard. Even more so, of course, when the pandemic hit.

What I mean by that is that I could not touch-type. Well, not with more than two fingers, because that is what I taught myself over the years without any formal training. So when the pandemic was in full swing, I decided to make the most of my time spent behind said keyboard and teach myself proper typing using the Colemak layout. I did not settle on Colemak immediately, though, and if you’re on the fence about it, I will take you through my journey.

What to learn?

Since I taught myself some poor man’s touch typing on regular QWERTY keyboards, I knew I would have to unlearn some elaborate muscle memory. At the same time, I knew QWERTY was not the only layout and that it definitely did not become a de facto standard because of its ergonomics. So I decided that since I started from scratch anyway, I would choose the appropriate layout for my needs. I have to warn you, though: you can (and probably will) get lost in a very deep rathole of keyboard layouts, with one of the layouts having amassed an even more passionate following than the other.

If you’re even half-serious about choosing a new layout, you will end up on carpalx, where you will read up on stroke paths, hand alternations, triads, and much more. Those values combined for all the different layouts result in a particular score that makes one of the layouts the best (QFMLWY) and another the worst (no, that’s not QWERTY, but TNWMLC, an anti-optimized layout with its own fashion line). Then you learn that the guy behind carpalx also collaborated on an article on the Dutch journalistic website De Correspondent to find the best Dutch layout. And you (or at least I, since I am Dutch) start to throw that in the comparison.

I will not judge you if, by this time, you have built an Excel with a dozen or so layouts, their total efforts for different languages, etc. Probably also around this time, perhaps instigated by that very Excel, you will have a momentary flashback of a kiss. Or, on second thought, a KISS – Keep It Simple, Stupid! You realize that you have started to optimize prematurely, which, according to scholars, is where evil lives.

Colemak layout

At this point, I made a quick decision to start with Colemak. It already is a massive improvement over QWERTY and also:

Leaves a lot of punctuation keys in the exact location – great for coding
It is quite popular and therefore supported quite well on various touch-type learning tools
It is supported out-of-the-box by macOS and iPadOS – this makes it super easy to switch to and from
Apparently also isn’t too bad for Dutch!

Note

If you are using Windows, there is a petition to get Colemak supported out-of-the-box as well.

How to learn?

There is, of course, only one trick to learning anything, and that is repetition. I made an effort to practice for at least 15 minutes every day. Those 15 minutes turned out to be a bit of a minimum, but also a maximum: practising any longer would negatively affect my accuracy increase my frustration, resulting in even lower accuracy. keybr.com keeps a nice log of your lessons:

Typing learing calendar

You see here that I kept at it for a couple of weeks and was practising a lot less after about four months. The good news is that by that time, I felt confident enough to switch to Colemak full-time! Practising as I went with business email, chat, etc. Everything was now done without looking at the keyboard and using all my fingers.

I do have to admit that I am not a fast typer. After a year of typing with Colemak, my top words-per-minute is 44. You can see progress in the graph below, but it’s not stellar by any measure. But honestly, I’m OK with that: it still feels great to type so effortlessly.

Typing speed increase. Green is speed, red is accuracy, and purple is the number of letters.

Regarding tools, I initially started with GNU Typist but later switched to keybr.com mentioned earlier. The great thing about it is that you can set the Colemak layout to be emulated instead of changing input sources on your OS. This allows you to quickly get some practice. The way it teaches you is excellent but brutal: it will focus on a couple of keys initially and let you practice until it measures that you are comfortable with them. Then it adds new keys to the mix, coming back every time to a specific key when it measures you’re losing confidence in it.

Whatever tool you decide to use, a typical recommendation is to use one that scores you primarily based on accuracy and then speed. As I have found out, your speed increase will be limited if you’re not accurate enough. Because, yeah, no matter how fast you can press backspace, that doesn’t count towards your WPM.

Remapping h/j/k/l

When you have taken the plunge, have spent some hours on keybr.com and are reasonably comfortable with the new layout, there will come a time when you run into challenges. For me, that was in the way to navigate in Vim/Neovim using h/j/k/l. Colemak moves the last three of those keys to different positions on the keyboard that are not intuitive at all. One easy solution is to use the arrow keys on your keyboard instead of h/j/k/l and forget about it. However, I grew pretty accustomed to the location of those keys, as they are in a great position on the home-row.

Then I remembered the concept of a layer on a keyboard that allows you to configure keys to act in a different way when you’re holding down a particular key. The Shift key can be seen as a modifier that activates the Capitals and Punctuation layer. And of course, there are the Ctrl, Alt and Cmd keys. Those seemed too far from the home row, and I chose to use the Escape key as a modifier to emulate arrow-key presses when the h/j/k/l keys are pressed.

Tip

For more inspiration, take a look at the Extend layer.

To remap these keys, you will need to use Karabiner Elements. With it, you can first do a simple modification to map Caps Lock to Escape (you didn’t think I would be using the regular Escape key, did you!?):

Then the tricky part comes where we need to add some complex modifications. My config is available in my dotfiles repo and does a couple of things:

Map Escape to Shift+Ctrl+Cmd+Option (also known as a Hyper-key), but only when held down: when there is a single press, the key will act as a regular Escape key.
Map Hyper + h/j/k/l to Left/Down/Up/Right keys
Map Hyper + y/u/i/o to Home/PgDwn/PgUp/End keys

Just to give you an idea, the first remap looks like this:

"manipulators": [
  { "from": {
      "key_code": "escape",
      "modifiers": {"optional": [ "any" ]}
    },
    "to": [
      {"key_code": "left_shift",
       "modifiers": ["left_control", "left_command", "left_option"]}
    ],
    "to_if_alone": [{"key_code": "escape"}],
    "type": "basic"
}]

If you want to use this remap config, download it from my repository and put it in the ~/.config/karabiner/assets/complex_modifications/ folder. The three remap configurations listed above can then be chosen in the Karabiner settings:

I’ve really come to enjoy this configuration for Vim, but the best thing is that I can now use the same Vim-like keys to navigate everywhere on my system: browsing in Firefox, writing in Word and calculating in Excel. Give it a try, and let me know what you think on Twitter!

Pictures of Japan

Sun, 31 May 2015 16:27:45 +0100

Info

This is an older post that I imported from my previous blog.

So today I’ve finally finished sorting, selecting and editing the pictures I took during my vacation in Japan. Me and my girlfriend were there for three weeks during the 2015 Sakura season.

You can view the full album on my Flickr page, but below you’ll find some of my favorites.

Business District

In Tokyo we stayed in a nice hotel in the middle of a busy business area. One of those neighbourhoods where the evenings during the week are more exciting than the weekends. Every restaurant is full of hard working salarymen letting of some steam.

Early bloom

Walking around Tokyo we stumbled across some cherry blossom trees that were already in full bloom, but most of them were still very much closed. This particular tree didn’t seem to have made up its mind and had some flowers that were already opening. Overall the sakura season started a bit early but as usual was very unpredictable. Luckily for us we caught the whole show during our stay.

Chillin'

Near Hiroshima we visited one of the biggest torii in Japan just of the Miyajima island. Here the deer have grown accustomed to the steady flow of tourists and they will attack for food. This one seemed pretty chilled out, though. Probably it already stole a big bag of sweets from an unsuspecting gaijin.

Japanese Jazz

One of the most fun evenings in Japan was hanging out in this small Jazz bar situated along the popular Pontochō alley. These guys were awesome and the lady behind the bar made us feel right at home. Definitely recommended: the Stardust Club.

Climbing

South of Kyoto on the Kii peninsula is an old trail called Daimon-zaka. It leads up on a big old mountain towards a quiet temple (especially compared to the tourist craziness in Kyoto) and is lined with trees that are hundreds of years old. It’s crazy to think old pelgrim monks already made the same trip and saw the same trees during the Edo-period. When you reach the top you are greeted by this beautiful view of a pagoda with the Nachi no taki waterfall behind it.

Watch out for bears

This is the old Nakasendo trail with a sign pointing towards one of the two post towns where it runs in between. Well, it used to be longer and was used as a route between Kyoto and Tokyo back in the old days, but nowadays this part is the only piece that is left as it was back then. Along the way you find several bells that can be rung to scare off any bears. We didn’t see any, so I guess they worked…

Grand Re-opening

Apparently we were in luck because Himeji castle — one of the very view castles that’s original — had been re-opened just a couple of weeks before we arrived. Unfortunately for us, Himeji castle is one of the most loved castles in Japan and because sakura was in full bloom when we were in the area, half of Japan was also there… The inside of the castle wasn’t very spectacular but I did love the outside!

Birthday View

A couple of days before we left I had my birthday and we booked a beautiful traditional Japanese hotel with a view from the roof on Mt. Fuji. The view was a bit blocked by the clouds, but we were still lucky to see part of it.

USB to Serial on Yosemite

Mon, 16 Mar 2015 11:27:45 +0100

Warning

This is an older post that I imported from my previous blog. I have not validated whether the procedure below is still relevant for Yosemite, but it most certainly will not be for newer macOS releases!

There have been numerous blog posts written on getting USB to Serial adapters working under Mac OS X — and specifically Yosemite. However, none of them gave me the absolute answer on how to get it working perfectly. And when a colleague of mine asked me to help him get his working on his Mac a couple of weeks ago, it seemed all was lost for him as well.

We followed the instructions on a couple of different web pages without any success and finally we just copied the driver I had running to his Mac and everything was working all of a sudden! Magic.

The driver I’m using took me a while to get right as well when I first started using a Mac some years ago. But since then it hadn’t failed me. Until of course Yosemite came along and required drivers to be signed:

com.apple.kextd[19]: ERROR: invalid signature for com.prolific.driver.PL2303, will not load

Luckily this was easily solved by running the following command and rebooting:

sudo nvram boot-args="kext-dev-mode=1"

The Correct Driver

Basically, there are two drivers available on the Internet for the Prolific USB to Serial chipset. The first is the Open Source version available on GitHub and the second is from a website called Plugable. As far as I can see the results are mixed for any of the adapters, but I’m using the latter.

When I first downloaded and installed this driver, it didn’t work until I made some changes in the Info.plist file included in the driver. To do so, I first unloaded the driver and opened the Info file:

sudo kextunload /System/Library/Extensions/ProlificUsbSerial.kext
sudo vi /System/Library/Extensions/ProlificUsbSerial.kext/Contents/Info.plist

In it you will find the 067B_2304 key which includes a certain idProduct and idVendor. These settings are the ones I had to change to reflect the following values:

    <key>067B_2304</key>                                                       
    <dict>                                                                     
        <key>CFBundleIdentifier</key>                                          
        <string>com.prolific.driver.PL2303</string>                            
        <key>IOClass</key>                                                     
        <string>com_prolific_driver_PL2303</string>                            
        <key>IOProviderClass</key>                                             
        <string>IOUSBInterface</string>                                        
        <key>bConfigurationValue</key>                                         
        <integer>1</integer>                                                   
        <key>bInterfaceNumber</key>                                            
        <integer>0</integer>                                                   
        <key>idProduct</key>                                                   
        <integer>8296</integer>                                                
        <key>idVendor</key>                                                    
        <integer>24969</integer>                                               
    </dict>

And when finished you can reload the kext-file: sudo kextload /System/Library/Extensions/ProlificUsbSerial.kext

Tested Devices

The known-working USB to Serial adapters for this driver are the following:

Sitecom USB to Serial Cable 0,6m CN-104
Trendnet USB to Serial Converter TU-S9 (Version v1.xR)

Please let me know on Twitter if it works for your device as well, or if you have any other questions.

Michiel Appelman

Setting up a Matrix Server with Cloudflare

Server Setup

Connecting with Ansible

Configuring the Playbook

Cloudflare Tunnel

Delegation and Discovery

Workers

R2 for Media Storage

Webhook Notifications

Deleting a Webhook

Running an IPv6-only webserver

Choosing the right server

Cloudflare Tunnel

Add an SSH Service

Protect the SSH Application

Connect from a terminal

Further Reading

Ditching QWERTY

What to learn?

How to learn?

Remapping h/j/k/l

Pictures of Japan

Business District

Early bloom

Chillin'

Japanese Jazz

Climbing

Watch out for bears

Grand Re-opening

Birthday View

USB to Serial on Yosemite

The Correct Driver

Tested Devices