Mozilla Services Documentation Tarek Ziade Aug 13, 2021 Contents 1 How To.. 3 2 Services 13 3 Client Development 45 4 Miscellaneous 69 Index 73 i ii Mozilla Services Documentation Welcome to the Mozilla Services Documentation front page. This site contains technical information about the services and products provided by the Mozilla Services Team. Right now that means Firefox Sync. (There were additional services documented here in the past, but they’ve been reprecated). To contribute to this site, see About this Website. Contents 1 Mozilla Services Documentation 2 Contents CHAPTER 1 How To. 1.1 Run your own Sync-1.5 Server Mozilla does not provide any pre-packaged release of the Firefox Sync server. The easiest way to install a Sync Server is to checkout our repository and run a build in-place. Once this is done, Sync can be run behind any Web Server that supports the WSGI protocol. 1.1.1 Important Notes The sync service uses Firefox Accounts for user authentication, which is a separate service and is not covered by this guide. Note: By default, a server set up using this guide will defer authentication to the Mozilla-hosted accounts server at https://accounts.firefox.com. You can safely use the Mozilla-hosted Firefox Accounts server in combination with a self-hosted sync storage server. The authentication and encryption protocols are designed so that the account server does not know the user’s plaintext password, and therefore cannot access their stored sync data. Alternatively, you can also Run your own Firefox Accounts Server to control all aspects of the system. The process for doing so is currently very experimental and not well documented. 1.1.2 Prerequisites The various parts are using Python 2.7 and Virtualenv. Make sure your system has them, or install them: • Python 2.7 downloads: http://python.org/download/releases/2.7.6 • Virtualenv: http://pypi.python.org/pypi/virtualenv To build and run the server, you will also need to have these packages installed: 3 Mozilla Services Documentation • python-dev • make • git • c and c++ compiler For example, under a fresh Ubuntu, you can run this command to meet all requirements: $ sudo apt-get install python-dev git-core python-virtualenv g++ 1.1.3 Building the server Get the latest version at https://github.com/mozilla-services/syncserver and run the build command: $ git clone https://github.com/mozilla-services/syncserver $ cd syncserver $ make build This command will create an isolated Python environment and pull all the required dependencies in it. A local/bin directory is created and contains a gunicorn command that can be used to run the server. If you like, you can run the testsuite to make sure everything is working properly: $ make test 1.1.4 Basic Configuration The server is configured using an ini-like file to specify various runtime settings. The file “syncserver.ini” will provide a useful starting point. There is one setting that you must specify before running the server: the client-visible URL for the service. Open “./syncserver.ini” and locate the following lines: [syncserver] public_url= http://localhost:5000/ The default value of “public_url” will work for testing purposes on your local machine. For final deployment, change it to the external, publicly-visible URL of your server. By default the server will use an in-memory database for storage, meaning that any sync data will be lost on server restart. You will almost certainly want to configure a more permanent database, which can be done with the “sqluri” setting: [syncserver] sqluri= sqlite:////path/to/database/file.db This setting will accept any SQLAlchemy database URI; for example the following would connect to a mysql server: [syncserver] sqluri= pymysql://username:password @db.example.com/sync 4 Chapter 1. How To. Mozilla Services Documentation 1.1.5 Running the Server Now you can run the server using gunicorn and the provided “syncserver.ini” file. The simplest way is to use the Makefile like this: $ make serve Or if you’d like to pass additional arguments to gunicorn, like this: $ local/bin/gunicorn --threads 4 --paste syncserver.ini Once the server is launched, you need to tell Firefox about its location. To configure desktop Firefox to talk to your new Sync server, go to “about:config”, search for “iden- tity.sync.tokenserver.uri” and change its value to be the public URL of your server with a path of “token/1.0/sync/1.5”: • identity.sync.tokenserver.uri: http://localhost:5000/token/1.0/sync/1.5 Alternatively, if you’re running your own Firefox Accounts server, and running Firefox 52 or later, see the documen- tation on how to Run your own Firefox Accounts Server for how to configure your client for both Sync and Firefox Accounts with a single preference. Firefox for Android (“Daylight”, versions 79 and later) does support using a non-Mozilla-hosted Sync server. Before logging in, go to App Menu > Settings > About Firefox and click the logo 5 times. You should see a “debug menu enabled” notification. Go back to the main menu and you will see two options for a custom account server and a custom Sync server. Set the Sync server to the URL given above and then log in. To configure Android Firefox 44 up to 78 to talk to your new Sync server, just set the “identity.sync.tokenserver.uri” exactly as above before signing in to Firefox Accounts and Sync on your Android device. Important: after creating the Android account, changes to “identity.sync.tokenserver.uri” will be ignored. (If you need to change the URI, delete the Android account using the Settings > Sync > Disconnect. menu item, update the pref, and sign in again.) Non-default TokenServer URLs are displayed in the Settings > Sync panel in Firefox for Android, so you should be able to verify your URL there. Prior to Firefox 44, a custom add-on was needed to configure Firefox for Android. For Firefox 43 and earlier, see the blog post How to connect Firefox for Android to self-hosted Firefox Account and Firefox Sync servers. (Prior to Firefox 42, the TokenServer preference name for Firefox Desktop was “services.sync.tokenServerURI”. While the old preference name will work in Firefox 42 and later, the new preference is recommended as the old preference name will be reset when the user signs out from Sync causing potential confusion.) Since Firefox 18, Firefox for iOS has support for custom sync servers. The settings can be made in the Advanced Sync Settings in the Firefox account section, which are visible if you are not signed in with a Firefox account and have enabled the debug mode (tap 5 times on the version number). In order to use the custom sync server with Firefox 28, the token server’s url must not contain the path “/1.0/sync/1.5”. It is also important to configure a custom FxA content server (you may use the default https://accounts.firefox.com). 1.1.6 Further Configuration Once the server is running and Firefox is syncing successfully, there are further configuration options you can tweak in the “syncserver.ini” file. The “secret” setting is used by the server to generate cryptographically-signed authentication tokens. It is blank by default, which means the server will randomly generate a new secret at startup. For long-lived server installations this should be set to a persistent value, generated from a good source of randomness. An easy way to generate such a value on posix-style systems is to do: 1.1. Run your own Sync-1.5 Server 5 Mozilla Services Documentation $ head -c 20 /dev/urandom | sha1sum db8a203aed5fe3e4594d4b75990acb76242efd35 - Then copy-paste the value into the config file like so: [syncserver] ...other settings... secret= db8a203aed5fe3e4594d4b75990acb76242efd35 The “identity_provider” setting controls which server service can issue identity assertions for access to the service. By default it will accept identity assertions from the Mozilla-hosted account server at https://accounts.firefox.com. If you are hosting your own instance of Firefox Accounts, you should change this to your own domain: [syncserver] . other settings. identity_provider = https://accounts.example.com The “allow_new_users” setting controls whether the server will accept requests from previously-unseen users. It is allowed by default, but once you have configured Firefox and successfully synced with your user account, additional users can be disabled by setting: [syncserver] ...other settings... allow_new_users= false 1.1.7 Updating the server You should periodically update your code to make sure you’ve got the latest fixes. The following commands will update syncserver in place: $ cd /path/to/syncserver $ git stash # to save any local changes to the config file $ git pull # to fetch latest updates from github $ git stash pop # to re-apply any local changes to the config file $ make build # to pull in any updated dependencies 1.1.8 Running behind a Web Server The built-in server should not be used in production, as it does not really support a lot of load. If you want to set up a production server, you can use different web servers that are compatible with the WSGI protocol. For example: • Apache combined with mod_wsgi • NGinx with Gunicorn or uWSGI Note: Remember, you must set the syncserver.public_url option to the client-visible URL of your server. For example, if your server will be located at http://example.com/ff-sync/, the public_url should be set to this value in your config file: [syncserver] public_url= http://example.com/ff-sync/ 6 Chapter 1. How To. Mozilla Services Documentation Apache + mod_wsgi Here’s an example of an Apache 2.2 setup that uses mod_wsgi: