SAFE Drive lets you access your SAFE Network storage as if it is on your local drive. It implements a virtual drive for SAFE Network on Windows, Mac OS and Linux computers, and uses the nodejs fuse-bindings library.
Features available now are listed below along with work in progress and future plans, but at your own risk!
WARNING: This software is still 'alpha' and may lose or corrupt data. Also be aware that all software contains bugs, so it is important for you to ensure that your data is backed up appropriately.
- access your SAFE containers under
~/SAFE(i.e._public,_documents, _music, _video, _photos) - access directories and files using the command line (e.g.
ls,more,treeetc.) - create, save, copy and backup files using command the line (
cp,rsyncetc.) - load any SAFE Drive file from a regular application (direct save not yet supported, see plans)
- browse your SAFE public names under
~/SAFE/_publicNamesusingls - list the services, and any service container files for each of your public names
- mount the files shared via anyone's public name with
ls ~/SAFE/_webMounts/<public name> - read-only access any public files via the mounts under
ls ~/SAFE/_webMounts
- Online Docs using LibreOffice: Using LibreOffice you can load and save documents directly on your SAFE Drive. If you save under a SAFE URI others can read them using SAFE Drive's 'web mounts' feature. Using SAFE means your private documents are really private and secure, as well as accessible to you from any device with access to SAFE Network, anywhere in the world.
- Backup: You can copy changed files to a backup location and know they are SAFE and always accessible. On Linux
cp -ruorrsync -ruare recommended for this. - dWeb Blog: is an example of a blazingly fast website that you can adapt and modify to deploy to both Web and SAFE Network with a single command. Visit dWeb Blog to learn How to set up your own dWeb Site.
- safegit - Decentralised Git Source Code Control: is a script which enables you to publish a git repository to SAFE Network where others can clone it, and can submit pull requests back to you. Read about safegit and how to enjoy decentralised git using SAFE Network.
Let us know how you use SAFE Drive by submitting additions to this list in a message or pull request.
- support decentralised
gitby pushing to headless repositories anyone can access (see safegit above which allows this now, although other work is also ongoing) - provide a locally hosted web interface for decentralised git (similar to github)
- provide a decentralised github like web app, hosted on SAFE Network
- save application files to SAFE Drive. This works with some applications such as LibreOffice and Vim, but is not reliable for all applications, but you can instead copy manually or use
rsync - create public names and services:
- create decentralised domains
- upload a website to a domain
- mount web style services (e.g. RESTful LDP, WebDav, and Solid via SafenetworkJs)
- command line options to:
- mount a single resource at a specified mount path on the SAFE drive
- specify access permissions on a specified mounted path
- package SAFE Drive as an executable that can be downloaded and 'just works'
Suggestions and feature requests welcome: please submit as issues
NOTE: only Linux is supported so far, but feel free to test with Windows or Mac and report back - there are some notes on how to do this below.
This software is made available on the condition that no warranty is attached to it and any use of the software is entirely at your own risk (see LICENSE).
The SAFE Network is a truly autonomous, decentralised internet. This Secure Access For Everyone Network (SAFE) tackles the increasing risks to individuals, business and nation states arising from over centralisation: domination by commercial monopolies, security risks from malware, hacking, surveillance and so on. It's a new and truly open internet aligned with the original vision held by its creators and early users, with security, net neutrality and unmediated open access baked in.
The following are currently all unique to the SAFE Network (2019):
- all services are secure and decentralised, including a human readable DNS
- highly censorship resistant to DDoS, deep packet inspection and nation state filters
- truly autonomous network
- data is guaranteed to be stored and available, forever with no ongoing fees (pay once to store)
- truly decentralised 'proof of resource' (farming), and not 'proof of work' or 'proof of stake'
- scalable non-blockchain based storage not just of hashes of data, but the data itself
- scalable non-blockchain cryptographically secured currency (Safecoin) with zero transaction fees
SAFE Network operates using the resources of anonymous 'farmers' who are rewarded with Safecoin, which they can sell or use to purchase storage and other services on the network. Safecoin is efficent and scalable (non-blockchain based) secure and anonymous digital cash.
SAFE is an open source project of @maidsafe, a private company which is majority owned by a Scottish charity, both based in Scotland but which is decentralised with employees and contributors based around the globe.
SAFE Drive is currently in development so to use it you will need to set up a development environment using git, yarn and nodejs.
To use SAFE Drive, follow the How To Set-up SAFE Drive instructions. This covers how to get an account on SAFE Network, install the dependencies for your operating system, and set-up SAFE Drive for development. When you have done all that, you're ready to use SAFE Drive:
You can use SAFE Drive with the live or mock SAFE Network. To use it with the live network, start SAFE Browser (v11.1 or later) non-dev build and log into your SAFE Network account.
Then, to mount your drive at ~/SAFE, type:
node bin.js
This will normally bring SAFE Browser to the foreground, showing a popup in the browser window requesting access to your storage on behalf of SAFE Drive, so click 'Accept', and SAFE Drive should then be mounted on your local filesystem.
If SAFE Drive has mounted successfullly there will be a directory at ~/SAFE containing two sub-directories. So check that you get the following ouput to ensure it has mounted:
$ ls
_public _publicNames
Before trying to mount it again, ensure it is unmounted properly by typing:
pkill node ; sudo umount ~/SAFE
The above is 'overkill' but the quickest way to reset things at this stage of development.
Later SAFE Drive will be bundled as an executable for each platform. Techniques for this have been tested with a discontinued version called safenetwork-fuse v0.1.0, based on safe-cli-boilerplate, but have not been updated and don't work at this time.
This is the full procedure to set up everything you need for development with SAFE Network alpha2, live or mock networks.
To use SAFE Drive you will need an account on SAFE Network, which is currently in testing (see How do I create an account under https://safenetwork.tech/get-involved/).
We test mainly on Ubuntu 18 for now but SAFE Drive has been tried successfully on other distros, so if you succeed (or not) on another distro please create an issue to report your findings and we'll add a note below.
In addition to Ubuntu 18, we have reports of success on Debian, Arch, and Fedora.
On Ubuntu install dependencies with:
sudo apt-get install libfuse-dev xdg-utils
If your distro doesn't have libfuse-dev try:
sudo apt-get install libfuse2 xdg-utils
On Arch based distros try fuse2:
sudo apt-get install fuse2 xdg-utils
Windows has not yet been tested but there is a good chance that it will now work. If you want to try it out see the development section below. See this forum topic for more information. Note that the code has been updated since that topic and is more likely to work with Windows now, but has not been tested. Also, some of the instructions in that topic may have been superceded due to changes in SAFE Browser, so if anything doesn't work, check back here or post a question on the forum.
Mac OS has not yet been tested but it should work as it is similar to Linux. If you want to try it out see the development section below. See this forum topic for more information, and this post for working around a problem with SAFE Browser authorisation on Mac OSX. Note that some of the instructions in that topic may have been superceded due to changes in SAFE Browser, so if anything doesn't work, check back here or post a question on the forum.
Start the SAFE Browser and log into your SAFE account. The following assumes the live network and non-dev SAFE Browser, but for development you will normally the mock network. Details of how to use the mock network that are included under Development.
a) Assuming you are in the SAFE Drive directory type:
node bin.js
b) SAFE Browser should come to the front asking you to authorise SAFE Drive to access your files, so click 'Authorise'. If the popup doesn't appear see the 'note' below about unmounting.
c) Your SAFE Drive should now be mounted and you can test this as follows
Note: before trying to mount SAFE Drive, ensure it is unmounted properly by typing:
pkill node ; sudo umount ~/SAFE
The above is 'overkill' but the quickest way to reset things at this stage of development.
If SAFE Drive has mounted successfully there will be a directory at ~/SAFE containing two sub-directories. So open another terminal and check that you get the following ouput to ensure it has mounted:
$ ls
_public _publicNames
If that works you can try various file system commands, such as:
ls ~/SAFE/_public
ls ~/SAFE/_publicNames
# etc
If you have uploaded files to your SAFE account you will see them in the directory listings, and you can view their contents on the terminal with cat or more, copy them to your hard drive with cp and so on, or open them in an application.
You can also try tree ~/SAFE but if you have a lot of files this can take a long time to complete, particularly on the live network. Note: you may have to install tree first depending on your Linux distro.
You can just shut down your computer, but if you wish to unmount the drive for any reason, or if it stops working.
On Linux, type:
sudo umount ~/SAFE
If this fails, make sure you don't have any command line shells or the file manager open on a SAFE path.
If there is a problem internally, you may need to exit the process and unmount, in which case try:
pkill node ; sudo umount ~/SAFE
This software is in development and you are likely to encounter bugs, minor and serious, and you can help us fix these by submitting a report of what happened as an issue.
Before doing this, please try and capture some debugging output by mounting your drive using the following command, and then repeating the process that causes the error:
On Linux, capture debugging information as follows:
DEBUG=safe* node bin.js 2>&1 | tee debug.log
This will create a file debug.log next to the executable with useful logging including any error messages you see on the console. So once you trigger the error, stop the process with pkill node (in another window), and then upload the debug.log file with the report as a New issue.
IMPORTANT: please include your operating system/distro and version, SAFE Browser version, with step by step instructions on how to replicate the problem, as well as what happened and what you expected to happen. Plus anything else you think might help, thanks!
Pull requests are welcome of course, so if you would like to help with development or just want to run from source, see below.
SAFE Drive is a command line application based on safe-cli-boilerplate.
It is written in NodeJS using the fuse-bindings and safenetworkjs libraries, and is intended to be packaged as a stand-alone executable for Windows, Mac OS and Linux. Limitations on the packaging scheme mean that some files are placed next to the executable.
NOTE: packaging is not currently supported, although early tests were done to establish feasibility using safenetwork-fuse v0.1.0.
If you are not yet familiar with developing for SAFE Network, or have not previously used the 'mock' network to develop and test your code, please run through the SAFE Network Nodejs Tutorial before proceeding. Doing so should ensure you have all the pre-requisites and help you understand anything not made explicit in the instructions below.
If you intend to work on the code remember to fork on github and then clone your fork. The following just clones the main repo:
git clone https://github.com/theWebalyst/safenetworkjs
cd safenetworkjs
NODE_ENV=dev yarn
yarn link
Note: any time you yarn add <package> you need NODE_ENV=dev set in order to ensure the debug versions of safe-app-nodejs are installed.
If you intend to work on the code remember to fork on github and then clone your fork. The following just clones the main repo:
git clone https://github.com/theWebalyst/safe-drive
cd safe-drive
NODE_ENV=dev yarn
yarn link safenetworkjs
Note: any time you yarn add <package> you need NODE_ENV=dev set in order to ensure the debug versions of safe-app-nodejs are installed.
sudo apt-get install libfuse-dev libfuse2 xdg-utils
NOTE: you only need one of either libfuse-dev or libfuse2, and one may fail to install depending on which linux distro you have. So as long as one of them is installed your're good.
Start the SAFE Browser dev build in another terminal with:
safe-browser --debug
In the browser, create an account on the mock network.
In ./safe-drive, and ensure NODE_ENV=test is set to enable use of the mock network:
SAFENETWORKJS_TESTS=testing NODE_ENV=test DEBUG=safe* node bin.js
You should see output to the terminal, and assuming no errors the browser will come to the front and request access to your storage on behalf of SAFE Drive. On clicking 'Accept' SAFE Drive should be mounted and be accessible at ~/SAFE (on Linux).
If this does not work, check you have the latest SAFE Browswer dev-build.
Before mounting you should make sure SAFE Drive is not still mounted by typing:
pkill node ; sudo umount ~/SAFE
Note: SAFENETWORKJS_TESTS=testing is only needed when you intend to run the test scripts in ./tests. It is a signal to SafenetworkJS that tells it to create a public container (on your SAFE account) needed by the test scripts, if it doesn't already exist. To run the tests:
cd ./safe-drive/tests
./test-safedrive.sh mock
Or to omit some 'expensive' tests when using the live network:
./test-safedrive.sh live
More options are available and will be listed if you omit the parameter:
./test-safedrive.sh
SafenetworkJS and SAFE Drive use debug to provide decorated, filterable output to the console which is very helpful for debugging. You can control which files contribute to the debug output with the DEBUG environment variable.
For example, following command mounts SAFE Drive and tells it to produce debug output to the console, filtered to include statements starting with safe-fuse or safenetworkjs:
NODE_ENV=test DEBUG=safe-fuse*,safenetworkjs* node bin.js
If you want to capture the console debug output, append '2>&1 | tee debug.log' to the end of the command. This will capture a copy of the console output in debug.log. For example:
NODE_ENV=test DEBUG=safe-fuse*,safenetworkjs* node bin.js 2>&1 | tee debug.log
Each source file has it's own 'decoration' set where it imports the debug module, so see the source code to see what you should include in the DEBUG setting to enable or filter its output.
Note: too much debug output seems to cause SAFE Drive to stop at random points, so if you find this happening, try 'tightenitng' your DEBUG filters to reduce this.
Note: fuse-bindings generate output to the console when DEBUG is set, but without any decoration or filtering. So any lines that don't have decoration at the start are produced by the fuse-bindings module, which is also very helpful.
You can use the source code debugger in Chrome or Chromium to set breakpoints, inspect variables, view the stack and step through SAFE Drive and SafenetworkJs code.
To use the debugger, start Chrome or Chromium, navigate to about:inspect and click on the link. The debugger will open and display the source code of the entry point.
Then, start SAFE Drive as before but with an additional flag: --inspect-brk (or --inspect to run immediately). For example
NODE_ENV=test DEBUG=safe-fuse*,safenetworkjs* node --inspect-brk bin.js
Before requesting help here, please follow the SAFE Network Nodejs Tutorial and ensure you are able to build a desktop app. That should ensure you have all the pre-requisites, and help you to understand how to test using a mock SAFE Network.
If you have problems with the tutorial please post on the SAFE Network developer forum rather than here.
Pull requests are welcome for outstanding issues and feature requests. Please note that contributions are subject to the LICENSE (see below).
IMPORTANT: By submitting a pull request, you will be offering code under the LICENSE (below).
Before submitting your code please consider using Standard.js formatting. You may also find it helps to use an editor with support for Standard.js when developing and testing. An easy way is just to use Atom IDE with the package [ide-standardjs] (and optionally standard-formatter). Or you can install NodeJS Standard.js.
This project is made available under the GPL-3.0 LICENSE except for individual files which contain their own license so long as that file license is compatible with GPL-3.0.
The responsibility for checking this licensing is valid and that your use of this code complies lies with any person and organisation making any use of it.