Documentation cleanup: tablet.md

[murchu27]

As highlighted in #113 by @Myridium, some parts of the documentation could do with some rewording or expanding, to make it easier to understand.

We'll address their questions on tablet.md here:

• [ ] 1. It says "There are several ways to make it work, choose whatever works for you". Make what work? Then, there are three (four?) methods listed. The first uses a heading which is a smaller font size and says Automatic. Then, Variant 1, Variant 2 and Variant 3 are listed afterwards. I take this to mean that the first part is, well, automatic and I can skip it. But then why would it be listed? I'm not sure. It asks me to just run an "automagic" script, so I guess you mean it's a script. I don't know what the word automatic adds here except to confuse. You could say that it automates the first setup variant Variant 1 when you run the script. It also has no explanation about the changes that will make to my ReMarkable, how to do undo those changes if required, but also no explanation for how it will automatically know what my custom server's domain name is. The script cannot possibly know that. This cannot be automatically accomplished. So what is this script? It is listed as an alternative to any of the following methods, but it cannot possibly be fully automated. If it's an interactive script then you should say so.
• [ ] 2. generate a CA and host certificate for .appspot.com -- is the .appspot.com to be taken literally, or do we fill in our hostname somewhere? This would be cleared up if it was explained what the purpose of doing this is. I don't know what appspot.com is.
• [ ] 3. The quote: A reverse proxy rmfakecloud-proxy has to be installed run rmfakecloud on whichever port you want, you can use either HTTP (not recommended) or HTTPS, generate a new cert for the url you chose e.g with Let's Encrypt. There are two run-on sentences here ...has to be installed run rmfakecloud... and also ...you can use [x], generate a new.... Also, where should the reverse proxy installed? On the tablet or on the rmfakecloud host? Why do I have to use a custom reverse proxy program, when reverse proxying is a routine procedure for networking applications? What does the script actually do? What do you mean by you can use either HTTP or HTTPS? What does use HTTP or use HTTPS mean in this context? One does not "use HTTP/s" when installing a reverse proxy. One can configure HTTP, and one can configure HTTPS, and these are not mutually exclusive options. Moreover the reMarkable sync protocol is, well, a protocol. We don't have control over whether it uses HTTP or HTTPS, so I cannot understanding the meaning of this. It's not a choice we can make-- we must use whatever the protocol demands. All of this can be clarified if you explain what the purpose of this reverse-proxy software is. I can only take a guess: does it take the reMarkable sync protocol traffic (which was redirected to 127.0.0.1 via modifying the hosts file) and redirect it to our custom server? In that case, why not just use our server's IP or hostname in hosts? Does using a reverse proxy somehow get around a invalid certificate problem? I don't know. I don't know what the reverse proxy's role is in all of this, and I'm just inferring the purpose of 127.0.0.1 redirects in the hosts file. You should explain what each step is doing and why.
• [ ] 4. set the STORAGE_URL to point to this address (this thing the device can resolve/see e.g the reverse proxy, public dns etc) -- it says set the STORAGE_URL. So, it's not an environment variable to be exported to be used by the next script fixsync.sh. So what exactly is the STORAGE_URL? No idea.
• [ ] 5. generate the certs from Variant 1, you get them (proxy.crt, proxy.key, ca.crt) and trust the ca.crt - how does one trust the ca.crt? If I knew more about using certificate authorities, then I would understand this. But I don't know and I don't understand.
• [ ] 6. Windows/Mac Desktop Client -- wait what? Client software? What client software? I thought this was server software. ???
• [ ] 7. modify the hosts file (\system32\drivers\etc\hosts) add the same entries as on the tablet -- this makes no sense. The host machine does not need its hosts file changed. What? Oh, are you referring to the ReMarkable apps on Windows and Mac? Then in Variant 3:
• [ ] 8. Same as Variant2, but instead of modifying any hosts file, make the changes on your DNS/router: add the host entries directly on your router (Hosts in OpenWRT) -- it's really annoying have to back-check and cross-validate steps across methods. Please just copy/paste. It takes no time and it makes it easier to understand. Also what is the hosts entry on my router? I've never heard of such a thing, and most routers certainly wouldn't allow changing it. Also why do we have to change anything with our router? Router connected to the network of the host or the tablet? We don't necessarily have control over either. This whole thing doesn't make sense. Also what the heck is OpenWRT? Never heard of that either.
• [ ] 9. trust the ca.crt - again, don't know how, or why. In fact I don't even know where to find ca.crt.
• [ ] 10. I don't think it says anywhere here what records to actually add to the DNS. So I don't know what the DNS settings have to do with this variant.
• [ ] 11. PROS: a bit easier, you can you even the mobile apps if you manage to install the root ca. CONS: you can't use the official cloud anymore due to the mangled DNS. How does one "install a root certificate authority". One cannot "install a certificate authority". I guess you mean the certificate? Why would we install the certificate that generated earlier...? I don't even understand why we generated that certificate (or how, since you say for *.appspot.com but I don't own that domain so how could I generate a certificate for it?), much less why the certificate should be required on the devices which hook into rmfakecloud.
• [ ] 12. you can't use the official cloud anymore due to the mangled DNS well considering the instructions did not include any changes to the DNS settings, I think it'll be fine.

[murchu27]

@ddvk could you comment on 5-12, I haven't used variants 2 and 3 myself

[ddvk]

1. the tablet should be redirected to rmfakecloud in some way, there are a couple of ways to do that automatic/magic does variant 1, the descriptions are just the manual steps that have be done in order for that to work. the automagic is the default/recommended way, the rest are just options for advanced users (some were not ok with having a reverse proxy running on the tablet)
2. it involves using openssl to generate a self signed certificate authority (which the automagic script does). you add the ca.crt in
   to the list of trusted ca's (in windows mmc->certificates, in mac keychain i think)
3. About making the official desktop clients work with rmfakecloud
4. the hosts file on the desktop where the official client is installed
5. this is an advanced use case. by modifying the dns of your router (assuming at home you have controll etc) you make all dns queries to remarkable resolve to something else. openwrt is an open source firmware you can install on some home routers.
6. the ca.crt that you generated or the one that was generated on the tablet
7. all remarkable cloud addesses (listed in variant1) have to point to the ip where rmfakecloud is running
8. you open the ca.crt on the device (by hosting it somewhere, sending it via email), recent android versions don't allow it anymore without tweaks iirc
9. if you change the dns on the router (8.), noone else will be able to use the official cloud

[Myridium]

Thanks @ddvk , that clears most things up for me.