Installation/Camo: Difference between revisions

From diaspora* project wiki
(update notice)
No edit summary
 
(19 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Serious|Camo integration for diaspora* is not yet in a released version. This documentation is a work in progress so it is ready when the Camo integration is released.}}
{{Serious|There seems to be an issue with Camo sometimes not loading images when using recent Node.js versions. While we continue diagnosing the issue further, using the Node.js Boron LTS tree (Version 6.x) as a temporary workaround works fine.}}


[[File:Markdown_embeds_without_Camo.svg|thumb|right|200px|Request targets, without Camo]]
[[File:Markdown_embeds_without_Camo.svg|thumb|right|200px|Request targets, without Camo]]
Line 33: Line 33:
cd camo
cd camo
npm install
npm install
rake bundle
|lang=bash}}
|lang=bash}}


Line 39: Line 38:


{{#tag:syntaxhighlight|
{{#tag:syntaxhighlight|
coffee server.coffee
CAMO_KEY="..." node server.js
|lang=bash}}
|lang=bash}}


You should add a service file to your system to ensure the service is up all the time. Please check https://github.com/atmos/camo#configuration for available and required configurations and generate a shared key for the HMAC generation.
You should add a service file to your system to ensure the service is up all the time. '''Please check https://github.com/atmos/camo#configuration for available and required configurations.''' Generate a shared key for the HMAC generation (for example using <code>pwgen -sy 64</code>, but make sure your key does not contain a backslash).


=== Setting up the reverse proxy ===
=== Setting up the reverse proxy ===
Line 48: Line 47:
A reverse proxy should be used to connect your Camo instance to the world. By using the server running diaspora*, it is possible to run Camo inside a virtual subdirectory so you do not need a dedicated subdomain. That is handy if you do not own a wildcard certificate.
A reverse proxy should be used to connect your Camo instance to the world. By using the server running diaspora*, it is possible to run Camo inside a virtual subdirectory so you do not need a dedicated subdomain. That is handy if you do not own a wildcard certificate.


Here is an example config for nginx, but you should be able to create a version for Apache very easily:
Here is an example config for nginx:


{{#tag:syntaxhighlight|
{{#tag:syntaxhighlight|
upstream camo {
upstream camo {
     server 127.0.0.1:9090;
     server 127.0.0.1:8081;
}
}


Line 61: Line 60:
     break;
     break;
}
}
|lang=text}}
And here's one for apache with ''mod_rewrite'' and ''mod_proxy'' enabled:
{{#tag:syntaxhighlight|
RewriteEngine On
RewriteRule ^/camo/(.*)$ balancer://camo/$1 [P,L]
<Proxy balancer://camo>
    BalancerMember http://127.0.0.1:8081
</Proxy>
|lang=text}}
|lang=text}}


Line 72: Line 81:


== Recommended Camo settings ==
== Recommended Camo settings ==
=== Camo variables ===


Tests have shown disabling a strict SSL certificate check is a good idea to avoid problems with images from hosts with self-signed certificates (or CACert certificates, if CACert is not in your systems bundle). Also increasing the max file size to 10MiB is recommended due to the large size of some GIFs - and diaspora* loves GIFs. To apply those suggestions, set the following environment variables when starting Camo:
Tests have shown disabling a strict SSL certificate check is a good idea to avoid problems with images from hosts with self-signed certificates (or CACert certificates, if CACert is not in your systems bundle). Also increasing the max file size to 10MiB is recommended due to the large size of some GIFs - and diaspora* loves GIFs. To apply those suggestions, set the following environment variables when starting Camo:
Line 78: Line 89:
NODE_TLS_REJECT_UNAUTHORIZED=0
NODE_TLS_REJECT_UNAUTHORIZED=0
CAMO_LENGTH_LIMIT=10485760
CAMO_LENGTH_LIMIT=10485760
CAMO_HEADER_VIA="Camo Asset Proxy at <Your pod URL>"
|lang=bash}}
|lang=bash}}


To avoid problems with images hosted on Amazon S3 or CloudFlares CDN, it's recommended to add two MIME types to the whitelist in Camos <code>mime-types.json</code>. Just append these to the list:
=== Mime types ===
 
To avoid problems with images hosted on Amazon S3 (used by joindiaspora.com) or CloudFlares CDN, it's recommended to add two MIME types to the whitelist in Camos <code>mime-types.json</code>. Just append these to the list:


{{#tag:syntaxhighlight|
{{#tag:syntaxhighlight|
"application/octet-stream",
"application/octet-stream",
"binary/octet-stream"
"binary/octet-stream",
""
|lang=javascript}}
|lang=javascript}}


Line 90: Line 105:


Please report bugs [[How_to_report_a_bug|the usual way]] and we will decide if it is an implementation bug or something caused by Camo and/or the remote host.
Please report bugs [[How_to_report_a_bug|the usual way]] and we will decide if it is an implementation bug or something caused by Camo and/or the remote host.
[[Category:Installation]]

Latest revision as of 11:04, 29 March 2018

WarningWarning:There seems to be an issue with Camo sometimes not loading images when using recent Node.js versions. While we continue diagnosing the issue further, using the Node.js Boron LTS tree (Version 6.x) as a temporary workaround works fine.
Request targets, without Camo
Request targets, with Camo

About Camo and why there is support for it in diaspora*

Camo is a small Node.js application to proxy insecure assets. Its main reason is to service HTTP assets over an HTTPS channel to avoid mixed content warnings. Another usage is to reduce the amount of external assets to avoid browser connects to third party hosts. Camo will also add a whitelisting to the images MIME type to add some protection against attacks.

diaspora* supports content formatting using Markdown, which also enables users to embed images from third parties. While this is great for creating larger posts with inline images, it is a huge privacy and security problem since most of the images will get hosted by third parties, forcing the users browser to connect to those servers, thus exposing their identities to others.

Since disabling markdown embeds is not a nice solution, we implemented a special mechanism to rewrite markdown image URLs to get proxied through Camo. In addition, it is also possible to proxy remote profile pictures and remote post photos to create an environment almost entirely without external resources.

Why your pod should enable Camo

  • Depending on your configuration, embedded images and/or remote pods content will get proxied through your server, so your user's browsers do not need to connect to external servers. This will increase the users privacy.
  • Your pods frontend will get a little bit of extra protection due to the MIME type whitelist.

Why your pod should not enable Camo

  • Camo will create a huge amount of traffic depending on your settings since it will proxy all the remote images.
  • You will have to maintain a dedicated node.js application, the Camo application is neither shipped nor started with diaspora*.
  • Bugs may occur and images with wrong/missing MIME types will not get served.

Adding Camo to your pod

Setting up Camo

First, you have to set up Node.js on your server. Detailed instructions are available on the Node.js website. Then get a copy of camo's source code and install its dependencies

git clone https://github.com/atmos/camo.git
cd camo
npm install

You are now able to start camo using

CAMO_KEY="..." node server.js

You should add a service file to your system to ensure the service is up all the time. Please check https://github.com/atmos/camo#configuration for available and required configurations. Generate a shared key for the HMAC generation (for example using pwgen -sy 64, but make sure your key does not contain a backslash).

Setting up the reverse proxy

A reverse proxy should be used to connect your Camo instance to the world. By using the server running diaspora*, it is possible to run Camo inside a virtual subdirectory so you do not need a dedicated subdomain. That is handy if you do not own a wildcard certificate.

Here is an example config for nginx:

upstream camo {
    server 127.0.0.1:8081;
}

# inside your diaspora* config
location /camo/ {
    proxy_redirect off;
    proxy_pass http://camo/;
    break;
}

And here's one for apache with mod_rewrite and mod_proxy enabled:

RewriteEngine On
RewriteRule ^/camo/(.*)$ balancer://camo/$1 [P,L] 

<Proxy balancer://camo>
    BalancerMember http://127.0.0.1:8081
</Proxy>

Setting up diaspora*

You have to enable and configure the Camo integration in your diaspora.yml, example configuration values and explanations are available inside diaspora.yml.example. Please ensure you considered the amount of users and traffic before enabling proxy modes. Here is a short summary:

  • proxy_markdown_images will enable proxying for all images embedded via markdown. This is recommended, but pay attention if you have a large number of users since it might cause some traffic.
  • proxy_opengraph_thumbnails will proxy thumbnails of OpenGraph embeds. You can turn this on since there are not much OpenGraph embeds right now.
  • proxy_remote_pod_images will proxy all remote images including profile pictures and photos inside posts. Enabling this will create a very private environment, but proxing all those images will create a huge amount of traffic.

Recommended Camo settings

Camo variables

Tests have shown disabling a strict SSL certificate check is a good idea to avoid problems with images from hosts with self-signed certificates (or CACert certificates, if CACert is not in your systems bundle). Also increasing the max file size to 10MiB is recommended due to the large size of some GIFs - and diaspora* loves GIFs. To apply those suggestions, set the following environment variables when starting Camo:

NODE_TLS_REJECT_UNAUTHORIZED=0
CAMO_LENGTH_LIMIT=10485760
CAMO_HEADER_VIA="Camo Asset Proxy at <Your pod URL>"

Mime types

To avoid problems with images hosted on Amazon S3 (used by joindiaspora.com) or CloudFlares CDN, it's recommended to add two MIME types to the whitelist in Camos mime-types.json. Just append these to the list:

"application/octet-stream",
"binary/octet-stream",
""

Reporting issues

Please report bugs the usual way and we will decide if it is an implementation bug or something caused by Camo and/or the remote host.