## 1. Project Overview & Quickstart (ipfs/ipfs-desktop) ## File: README.md # IPFS Desktop [](https://ipfs.tech) [](https://discuss.ipfs.tech) [](https://github.com/ipfs/ipfs-desktop/actions?query=branch%3Amain) [](https://github.com/ipfs/ipfs-desktop/releases/tag/v0.50.0) **IPFS Desktop gives you all the power of [IPFS](https://ipfs.tech) in a convenient desktop app: a complete IPFS node, plus handy OS menubar/taskbar shortcuts and an all-in-one file manager, peer map, and content explorer.** Use IPFS Desktop to get acquainted with IPFS without needing to touch the terminal — or, if you're already experienced, use the powerful menubar/taskbar shortcuts alongside the command line to make your IPFS workflow faster. | Files screen | Explore screen | Peers screen | Settings screen | Menubar/taskbar | |-------|---------|-------|----------|------| | | | | | | ### Quick-install shortcuts When in doubt, pick one of package formats with built-in automatic update mechanism: - **Windows:** [ipfs-desktop-setup-0.50.0-win-x64.exe](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-setup-0.50.0-win-x64.exe) - **Mac:** [ipfs-desktop-0.50.0-mac.dmg](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-mac.dmg) - **Linux:** [ipfs-desktop-0.50.0-linux-x86_64.AppImage](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x86_64.AppImage) - If you prefer to manage updates on your own, see [other package formats](#install) below. ### Table of Contents - [Features](#features) - [Start your node at system startup and control it from your OS](#start-your-node-at-system-startup-and-control-it-from-your-os) - [Quickly import files, folders, and screenshots to IPFS](#quickly-import-files-folders-and-screenshots-to-ipfs) - [Easily manage the contents of your node](#easily-manage-the-contents-of-your-node) - [Visualize your IPFS peers worldwide](#visualize-your-ipfs-peers-worldwide) - [Explore the "Merkle Forest" of IPFS files](#explore-the-merkle-forest-of-ipfs-files) - [Enjoy OS-wide support for IPFS files and links](#enjoy-os-wide-support-for-ipfs-files-and-links) - [Learn IPFS commands as you go](#learn-ipfs-commands-as-you-go) - [Install](#install) - [Windows](#windows) - [Mac](#mac) - [Linux/FreeBSD](#linuxfreebsd) - [Install from source](#install-from-source) - [Contribute](#contribute) - [Translations](#translations) - [Developer notes](#developer-notes) - [FAQ & Troubleshooting](#faq--troubleshooting) - [Why am I missing the system tray menu on Linux?](#why-am-i-missing-the-system-tray-menu-on-linux) - [Why can't I install IPFS Desktop under Debian 11?](#why-cant-i-install-ipfs-desktop-under-debian-11) - [Why can't I start IPFS Desktop under Debian 10?](#why-cant-i-start-ipfs-desktop-under-debian-10) - [Why does the AppImage fail with a FUSE error?](#why-does-the-appimage-fail-with-a-fuse-error) - [`GTK 2/3 symbols detected. Using GTK 2/3 and GTK 4 in the same process is not supported`](#gtk-23-symbols-detected-using-gtk-23-and-gtk-4-in-the-same-process-is-not-supported) - [Where are my configuration and log files?](#where-are-my-configuration-and-log-files) - [IPFS Desktop configuration](#ipfs-desktop-configuration) - [Kubo repository and configuration](#kubo-repository-and-configuration) - [How does IPFS Desktop select the IPFS repo location?](#how-does-ipfs-desktop-select-the-ipfs-repo-location) - [Which operating systems are supported?](#which-operating-systems-are-supported) - [Which version of IPFS does IPFS Desktop use?](#which-version-of-ipfs-does-ipfs-desktop-use) - [Which flags does IPFS Desktop boot with?](#which-flags-does-ipfs-desktop-boot-with) - [I got a `repo.lock` error. How do I resolve this?](#i-got-a-repolock-error-how-do-i-resolve-this) - [I got a network error (e.g. `Error fetching`). What should I do?](#i-got-a-network-error-eg-error-fetching-what-should-i-do) - [Error: Initializing daemon...](#error-initializing-daemon) - [Error: Your programs version (N) is lower than your repos (N+x).](#error-your-programs-version-n-is-lower-than-your-repos-nx) - [Found outdated fs-repo, migrations need to be run. - Error fetching: context deadline exceeded](#found-outdated-fs-repo-migrations-need-to-be-run---error-fetching-context-deadline-exceeded) - [The daemon failed to start and produced no output. What now?](#the-daemon-failed-to-start-and-produced-no-output-what-now) - [I need more help!](#i-need-more-help) - [License](#license) ## Features IPFS Desktop combines a complete IPFS node (running [kubo](https://github.com/ipfs/kubo)) and the [IPFS Web UI](https://github.com/ipfs/ipfs-webui) into a single, convenient desktop app — plus adds a menu to your OS menubar/system tray for easy access to a variety of common IPFS tasks. If you already have an IPFS node on your computer, IPFS Desktop will act as a control panel and file browser for that node. If you don't have a node, it'll install one for you. And either way, IPFS Desktop will automatically check for updates. ### Start your node at system startup and control it from your OS IPFS Desktop enables you to stop or restart your node straight from the IPFS logo menu in your OS menubar/system tray. For Mac and Windows users, IPFS Desktop can also be set to launch at system startup, ensuring that your node is running whenever your computer is on. ### Quickly import files, folders, and screenshots to IPFS Import files and folders to your IPFS node in a variety of convenient ways: - Drag and drop items onto IPFS Desktop's `Files` screen - Click the `Import` button on the `Files` screen to add items from your computer or an IPFS [content ID (CID)](https://docs.ipfs.tech/concepts/content-addressing/#identifier-formats) - (Windows) Right-click a file/folder's icon to add it to IPFS from the pop-up menu - (Mac) Drag and drop a file/folder onto the IPFS logo in your menubar Plus, you can use the `Take Screenshot` command under the IPFS logo menu to take a screenshot, import it to your node, and copy a shareable link to your clipboard with one click. ### Easily manage the contents of your node IPFS Desktop's `Files` screen gives you an easy, familiar interface for working with the contents of your node: - Easily rename, move, or remove files and folders - Preview many common file formats directly in IPFS Desktop - Copy a file/folder's IPFS [content ID (CID)](https://docs.ipfs.tech/concepts/content-addressing/#identifier-formats) or a shareable link to your clipboard - ["Pin"](https://docs.ipfs.tech/concepts/persistence/) files to your IPFS node or to a [third-party pinning service](https://github.com/ipfs/pinning-services-api-spec) ### Visualize your IPFS peers worldwide Visit the `Peers` screen to see what nodes you're connected to, where they are, the connections they're using, and more. ### Explore the "Merkle Forest" of IPFS files Use the `Explore` screen to explore some example datasets — or your own files — and see firsthand how items stored on IPFS are broken down into content-addressed pieces. ### Enjoy OS-wide support for IPFS files and links IPFS Desktop enables most operating systems (Mac, Windows and some Linux flavors) to support protocols including `ipfs://` and `ipns://`. This means that if an app on your computer tries to open a link starting with one of those protocol identifiers (for example, if your web browser encounters a link to `ipns://en.wikipedia-on-ipfs.org`), it'll automatically open in IPFS Desktop. For an even better experience with `ipfs://`, and `ipns://` addresses, we also recommend installing [IPFS Companion](https://github.com/ipfs/ipfs-companion) to add support in your favorite browser! ### Learn IPFS commands as you go If you're interested in learning how to use IPFS from the command line, IPFS Desktop's CLI Tutor Mode can show you common IPFS commands as you go. Just check the `CLI Tutor Mode` box on the `Settings` screen to switch on this feature. ## Install Release notes and older versions of IPFS Desktop can be found on the [releases page](https://github.com/ipfs/ipfs-desktop/releases). Don't see your favorite package manager? Visit our [package managers page](https://github.com/ipfs/ipfs-desktop/issues/691) and help us add support for it! ### Windows - **Installer:** [ipfs-desktop-setup-0.50.0-win-x64.exe](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-setup-0.50.0-win-x64.exe)\ [](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-setup-0.50.0-win-x64.exe) - **Chocolatey** (community-maintained): `choco install ipfs-desktop` - **Scoop** (community-maintained): `scoop bucket add extras; scoop install extras/ipfs-desktop` - **WinGet** (community-maintained): `winget install IPFS.IPFS-Desktop` - ℹ️ update checks from existing users: [](https://github.com/ipfs/kubo/releases/latest) ### Mac - **Installer:** [ipfs-desktop-0.50.0-mac.dmg](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-mac.dmg)\ [ ](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-mac.dmg) - **Homebrew** (community-maintained): `brew install --cask ipfs` - ℹ️ update checks from existing users: [](https://github.com/ipfs/kubo/releases/latest) ### Linux/FreeBSD - **AppImage**: [ipfs-desktop-0.50.0-linux-x86_64.AppImage](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x86_64.AppImage)\ [](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x86_64.AppImage) - **Tarball (tar.gz)** (use this for building packages for distros): [ipfs-desktop-0.50.0-linux-x64.tar.xz](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x64.tar.xz)\ [](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x64.tar.xz) - **Debian (DEB)** (experimental): [ipfs-desktop-0.50.0-linux-amd64.deb](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-amd64.deb)\ [](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-amd64.deb) - **Red Hat (RPM)** (experimental): [ipfs-desktop-0.50.0-linux-x86_64.rpm](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x86_64.rpm)\ [](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x86_64.rpm) - **FreeBSD** (experimental): [ipfs-desktop-0.50.0-linux-x64.freebsd](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x64.freebsd) (requires [Linux Binary Compatibility to be enabled](https://docs.freebsd.org/en/books/handbook/linuxemu/))\ [](https://github.com/ipfs/ipfs-desktop/releases/download/v0.50.0/ipfs-desktop-0.50.0-linux-x64.freebsd) - **Snapcraft** support is deprecated and discouraged due to [confinement issues](https://github.com/ipfs/ipfs-desktop/issues/2031), use `.AppImage` instead - ℹ️ update checks from existing users: [](https://github.com/ipfs/kubo/releases/latest) Additional third-party packages exist, but have the built-in auto-update mechanism disabled. Instead, update cycle is maintained by respective communities: [](https://repology.org/project/ipfs-desktop/versions) ### Install from source To install and run IPFS Desktop from source, you'll also need: - [Node.js](https://nodejs.org/en/) – pick the current LTS - Any [platform-specific dependencies](https://github.com/nodejs/node-gyp#installation) required by [`node-gyp`](https://github.com/nodejs/node-gyp) Then, follow the steps below to clone the source code, install dependencies, and run the app. ```bash git clone https://github.com/ipfs/ipfs-desktop.git cd ipfs-desktop npm ci npm run build npm start ``` > **Build Note:** `npm ci` will download the webui code to run in electron from IPFS using the [ipfs-or-gateway](https://www.npmjs.com/package/ipfs-or-gateway) npm package. For details, see the [build process](.github/workflows/ci.yml) and the [webui code](https://github.com/ipfs/ipfs-webui). > **Local webui development:** to test with a local build of [ipfs-webui](https://github.com/ipfs/ipfs-webui), set `IPFS_WEBUI_PATH` to point at the webui build output directory. This copies the local build into `assets/webui/` instead of downloading the release by CID: > ```bash > IPFS_WEBUI_PATH=../ipfs-webui/build npm run build > npm start > ``` IPFS Desktop in itself is a simple container that makes sure Kubo and IPFS Webui can work together in a standalone fashion and has access to other os-specific features like tray and contextual integrations. There are multiple ways to access IPFS Webui: - https://webui.ipfs.io/#/welcome - http://127.0.0.1:5001/webui (shipped with kubo) - IPFS Desktop itself All of these instances of IPFS Webui are the same but shipped slightly differently. The file you're seeing being downloaded is a specific release of IPFS Webui, i.e. v4.1.1 has content identifiers (CID) `bafybeiamycmd52xvg6k3nzr6z3n33de6a2teyhquhj4kspdtnvetnkrfim` which can be verified on the [IPFS Webui release page](https://github.com/ipfs/ipfs-webui/releases). ## Contribute We welcome all contributions to IPFS Desktop! The best way to get started is to check the current [open issues](https://github.com/ipfs/ipfs-desktop/issues) (or drill down specifically for [issues labeled "help wanted"](https://github.com/ipfs/ipfs-desktop/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)) and find something interesting. All issues are categorized by the [standard label taxonomy](https://github.com/ipfs/community/blob/master/ISSUE_LABELS.md) used across the IPFS project, so you can also drill by topic (for example, [UX-related issues](https://github.com/ipfs/ipfs-desktop/issues?q=is%3Aissue+is%3Aopen+label%3Atopic%2Fdesign-ux)). No matter how you contribute, please be sure you read and follow the [IPFS Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) and the [IPFS Community Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). ### Translations Contributing translations in your language is particularly valuable! We use Transifex to manage internationalization, which means you don't need to change a single line of code to add your translations — just sign up for a Transifex account. Because IPFS Desktop app includes text from [IPFS Web UI](https://github.com/ipfs/ipfs-webui) and [IPLD Explorer Components](https://github.com/ipfs/ipld-explorer-components/), you'll want to join all three Transifex projects in order to see all the text: - https://explore.transifex.com/ipfs/ipfs-desktop/ - https://explore.transifex.com/ipfs/ipfs-webui/ - https://explore.transifex.com/ipfs/ipld-explorer/ *Note for developers: We use English as our source of truth. This means that if you add any new text, make those additions in [`./assets/locales/en.json`](./assets/locales/en.json) and they will automatically propagate in Transifex for other languages.* ### Developer notes For more detailed information about hacking on IPFS Desktop, including a release checklist, please see the full [developer notes](DEVELOPER-NOTES.md). ## FAQ & Troubleshooting ### Why am I missing the system tray menu on Linux? IPFS Desktop is built using Electron, and unfortunately, poor system tray support has been a [longstanding problem with Electron apps](https://github.com/electron/electron/issues/21445). You may wish to try troubleshooting according to the [Electron v9.3.0 docs](https://github.com/electron/electron/blob/v9.3.0/docs/api/tray.md#class-tray): - On Linux, the app indicator will be used if it is supported; otherwise `GtkStatusIcon` will be used - On Linux distributions that only have app indicator support, you must install `libappindicator1` to make the tray icon work If you've noticed that the old system tray is back in IPFS Desktop v0.13, this is because the Electron team [removed support for `StatusNotifier` and restored the old tray interface on Linux called `XEmbed`](https://github.com/electron/electron/issues/21445#issuecomment-634163402). ### Why can't I install IPFS Desktop under Debian 11? You can. `libappindicator3-1`, which no longer exists in Debian 11 and later, moved from `Depends` to `Recommends` in electron-builder, so apt installs and configures the package without it. The library is still what draws the system tray icon. If the icon is missing after install, either install it [on your own](https://gist.github.com/keyle/b4536dc922bb13d7b5dce16a7db7e328) or use `.AppImage` instead. ### Why can't I start IPFS Desktop under Debian 10? Some Linux users may see one of the following errors when trying to launch IPFS Desktop: When launching by double-clicking the app icon: > The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that chrome-sandbox is owned by root and has mode 4755. When launching from the terminal: ```console $ ipfs-desktop $Trace/breakpoint trap ``` This is a known issue with Electron/Chrome and some hardened kernels. More details can be found [here](https://github.com/ipfs/ipfs-desktop/issues/1362#issuecomment-596857282), but a fix is to start IPFS Desktop from the terminal with the following additional parameter: ```console $ ipfs-desktop --no-sandbox ``` The same error shows up on Ubuntu 24.04 and later, which restrict unprivileged user namespaces through AppArmor. It is most visible with the `.AppImage`, because its read-only mount cannot present `chrome-sandbox` as root-owned with mode 4755. To keep the sandbox, use the `.deb` instead: its post-install script sets the `chrome-sandbox` permissions to match your kernel and installs an AppArmor profile. ### Why does the AppImage fail with a FUSE error? If you see this error when running the AppImage: ``` dlopen(): error loading libfuse.so.2 AppImages require FUSE to run. ``` This happens because modern Linux distributions ship with FUSE 3, but AppImages currently require FUSE 2 (libfuse2). The two versions can coexist safely. **Fix by distribution:** | Distribution | Command | |--------------|---------| | Ubuntu 24.04+, Debian 13+ | `sudo apt install libfuse2t64` | | Ubuntu 22.04/23.x, Debian 12 | `sudo apt install libfuse2` | | Fedora | `sudo dnf install fuse-libs` | | Arch | `sudo pacman -S fuse2` | **Alternative:** Run without FUSE using extraction mode: ```console ./ipfs-desktop-*.AppImage --appimage-extract-and-run ``` > **Note:** This is a known limitation of the AppImage runtime used by electron-builder. Future releases may include a static runtime that removes this dependency. See [AppImage/AppImageKit#1120](https://github.com/AppImage/AppImageKit/issues/1120) for upstream progress. See [AppImage FUSE documentation](https://docs.appimage.org/user-guide/troubleshooting/fuse.html) for more details. ### `GTK 2/3 symbols detected. Using GTK 2/3 and GTK 4 in the same process is not supported` See [ipfs-desktop#2952](https://github.com/ipfs/ipfs-desktop/issues/2952). ### Where are my configuration and log files? > [!IMPORTANT] > IPFS Desktop uses [Kubo](https://github.com/ipfs/kubo) implementation of IPFS node, which has its own configuration and repository, separate from the Desktop app. #### IPFS Desktop configuration You can open Desktop app and log files from the IPFS logo menu by selecting `Open Logs Directory` or `Open Configuration File` from the `Advanced` submenu. Or, find them in your OS as follows: - **Mac:** `~/Library/Application Support/IPFS Desktop/` - **Windows:** `%APPDATA%\IPFS Desktop\` - **Linux:** `~/.config/IPFS Desktop/` #### Kubo repository and configuration To open your Kubo repo directory from the IPFS logo menu, select `Open Repository Directory` from the `Advanced` submenu. Or, find them in your OS as follows (assuming no custom `$IPFS_PATH` was set): - **Mac:** `$HOME/.ipfs/` - **Windows:** `%USERPROFILE%\.ipfs\` (`C:\Users\Username\.ipfs\`) - **Linux:** `$HOME/.ipfs/` Configuration file is named `.ipfs/config` ##### How does IPFS Desktop select the IPFS repo location? IPFS Desktop uses [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl) to locate Kubo repository. 1. First, it checks the `IPFS_PATH` environment variable. 2. If that isn't set, it falls back to `$HOME/.ipfs` (`%USERPROFILE%/.ipfs/` on Windows). As soon as the first run has succeeded, repository location info is saved in the configuration file, which becomes the source of truth. To open your Kubo repo directory from the IPFS logo menu, select `Open Repository Directory` from the `Advanced` submenu. ### Which operating systems are supported? | OS | Minimum version | |----|-----------------| | macOS | 12 Monterey, Intel and Apple Silicon | | Windows | 10, x64 and arm64 | | Linux | any release still supported by the distribution maker, x64 | This floor is set by [Electron](https://github.com/electron/electron#platform-support), which IPFS Desktop is built on, and by Go, which Kubo is built with. Neither ships binaries for older releases, so IPFS Desktop cannot start there even when the installer itself succeeds. Windows 7 is the one people hit most often, explained in more detail in [#2823](https://github.com/ipfs/ipfs-desktop/issues/2823#issuecomment-2163182898). Older IPFS Desktop builds are still on the [releases page](https://github.com/ipfs/ipfs-desktop/releases), but they get no fixes. If you are stuck on an older OS, the [IPFS forums](https://discuss.ipfs.tech/c/help/13) are the best place to ask. ### Which version of IPFS does IPFS Desktop use? IPFS Desktop includes its own embedded binary of Kubo (`kubo` version defined in `package.json`); this is the latest version of [Kubo](https://github.com/ipfs/kubo) that has passed QA for IPFS Desktop use. You can check which version of IPFS you're running from the IPFS logo menu by looking in the `About` submenu. ### Which flags does IPFS Desktop boot with? By default, IPFS Desktop starts the IPFS daemon with the flags `--migrate=true --enable-gc=true`. You can change this in the IPFS Desktop config file by selecting `Open Configuration File` from the `Advanced` submenu. ### I got a `repo.lock` error. How do I resolve this? In general, this means that a previous process was unable to remove the repository lock (indicator that file is in use) from the repository directory. This is supposed to be handled automatically, but sometimes it isn't. If you get this error, you can generally safely delete this file after shutting down any running IPFS daemon's or applications. Simple process is as follows: 1. Stop ipfs processes; 2. Manually delete lock file, located within the [repository](#how-does-ipfs-desktop-select-the-ipfs-repo-location); 3. Attempt to start ipfs desktop (or other process that received the `repo.lock` error) again. ### I got a network error (e.g. `Error fetching`). What should I do? When upgrading, IPFS may need to perform migrations and for that we need a stable connection to download the required information for the migrations. Sometimes, the Internet connection may fail or be blocked by firewalls or antiviruses, and then you will run into a network error. Before submitting an issue, please try the following: 1. Check if you are connected to the Internet; 2. Make sure your firewall or antivirus is not blocking requests, such as P2P traffic; 3. Try again, by restarting IPFS Desktop. ### Error: Initializing daemon... These errors pop up from [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl) when the Kubo daemon fails to start up. Below are some scenarios where you may run into this error. #### Error: Your programs version (N) is lower than your repos (N+x). This means you are attempting to run an older version of ipfs-desktop or Kubo than you have previously ran on your machine. Each Kubo version (which is included with ipfs-desktop) is tied to a specific IPFS repo version, which you can see at https://github.com/ipfs/fs-repo-migrations#when-should-i-migrate. The ideal solution is to ensure you're running [the latest version of ipfs-desktop](https://github.com/ipfs/ipfs-desktop/releases/latest), as upward migrations happen automatically. It is possible that your `PATH` has different kubo version than the one bundled with IPFS Desktop, in such case you should update it to [the latest kubo binary](https://github.com/ipfs/kubo/releases/latest) as well. However, if you are an advanced user and you really need to run the older version that is emitting this error, you will need to run a migration in reverse, manually. You can follow the official instructions [here](https://github.com/ipfs/fs-repo-migrations/blob/master/run.md) but with additional parameters: `fs-repo-migrations -revert-ok -to N`. See `fs-repo-migrations --help` for more information. #### Found outdated fs-repo, migrations need to be run. - Error fetching: context deadline exceeded This happens when there is a problem with downloading migrations needed by [fs-repo-migrations](https://github.com/ipfs/fs-repo-migrations/blob/master/run.md). The errors usually look something like this: ```bash Error: Initializing daemon... Kubo version: 0.22.0 Repo version: 14 System version: amd64/darwin Golang version: go1.19.12 Found outdated fs-repo, migrations need to be run. Looking for suitable migration binaries. Need 1 migrations, downloading. Downloading migration: fs-repo-13-to-14... Fetching with HTTP: "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions" Fetching with HTTP: "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions" Fetching with HTTP: "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions" Error fetching: exceeded number of retries. last error was http.DefaultClient.Do error: Get "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions": dial tcp 199.16.156.40:443: i/o timeout Fetching with IPFS: "fs-repo-13-to-14/versions" Error fetching: context deadline exceeded could not get latest version of migration fs-repo-13-to-14: 2 errors occurred: * exceeded number of retries. last error was http.DefaultClient.Do error: Get "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions": dial tcp 199.16.156.40:443: i/o timeout * ``` You can update your Kubo config to try different sources of the migration files. ##### With IPFS-Desktop 1. Go to the Settings tab 2. Find "Migrations" in the config, and update the `DownloadSources` array to be `["IPFS", "https://trustless-gateway.link", "HTTP"]` ##### From the terminal For this method, you have to have the `ipfs` binary available on your command line: ```bash ipfs config --json Migration.DownloadSources '["IPFS", "https://trustless-gateway.link", "HTTP"]' ``` ##### Manually in an editor (not recommended) You can also edit the config file (`~/.ipfs/config` or `C:\Users\Username\.ipfs\config`) manually. Just make sure the json file is valid when you finish. ### The daemon failed to start and produced no output. What now? This message means IPFS Desktop started the Kubo daemon, the daemon exited immediately, and it printed nothing on its way out. The cause is not in the message, so an issue that only quotes it cannot be acted on. The real error is in `error.log`. Open the IPFS logo menu, select `Open Logs Directory` from the `Advanced` submenu, and read the end of that file. The usual causes are: - antivirus or endpoint security removed, quarantined or blocked the bundled `ipfs` binary - the [Kubo repository](#kubo-repository-and-configuration) sits on a disk that is full, read-only, or no longer connected - another `ipfs` process is already using the same repository If the log points at one of the errors covered above, follow that section. Otherwise [open an issue](https://github.com/ipfs/ipfs-desktop/issues/new/choose) and paste the last 50 lines of `error.log` into it. ### I need more help! If you need help with using IPFS Desktop, the quickest way to get answers is to post them in the [official IPFS forums](https://discuss.ipfs.tech/c/help/13). If you think you've found a bug or other issue with IPFS Desktop itself, please [open an issue](https://github.com/ipfs/ipfs-desktop/issues/new/choose). ## License [MIT](./LICENSE) --- ## File: docs/FEATURES.md # Features offered by IPFS-Desktop This document is intended to capture the list of features offered by IPFS-Desktop, whether they're fully done, or in-progress. ## Legend - :grey_question: : Status unknown - 🥚 : In design phase - 🐣 : Work in progress - 🐥 : Try it out (implementation exists, but requires additional work or setup) - 🐓 : Shipped (works out of the box when ipfs-desktop is installed) ## Native OS features | Feature | Linux/BSD | macOS | Windows | | ---- | ---- | ---- | ---- | | System Tray/Menubar Icon | 🐓 |🐓 | 🐓 | | [Automatic updates](https://github.com/ipfs-shipyard/ipfs-desktop/issues/668) | 🐥 | 🐓 | 🐓 | | [System-wide protocol handler](https://github.com/ipfs-shipyard/ipfs-desktop/issues/807) | 🥚 | 🐓 | 🐓 | | [Dropbox-like mounting of MFS](https://github.com/ipfs-shipyard/ipfs-desktop/issues/618) | 🐣 | 🐣 | 🐣 | | ["Add to IPFS" from Native File Manager](https://github.com/ipfs-shipyard/ipfs-desktop/issues/678) | :grey_question: | :grey_question: | 🐓 | | [Add 'ipfs' to PATH](https://github.com/ipfs-shipyard/ipfs-desktop/issues/727) | 🥚 | 🥚 | 🥚 | ## Kubo related features | Feature | Linux/BSD | macOS | Windows | | ---- | ---- | ---- | ---- | | GUI for starting/stopping Kubo | 🐓 |🐓 | 🐓 | --- ## File: pkgs/chocolatey/README.md # Chocolatey Publishing - IPFS Desktop is available at https://chocolatey.org/packages/ipfs-desktop - Scripts present in this directory are automatically executed at CI after a new release is tagged ([#1697](https://github.com/ipfs-shipyard/ipfs-desktop/pull/1697)) ## 2. Official Technical Reference & Guides (ipfs/docs) ## File: README.md # THIS REPOSITORY IS BEING DEPRECATED **Heads up! On May 27th, this repository will be deprecated and replaced with [`ipfs/ipfs-docs`](https://github.com/ipfs/ipfs-docs). This repository will not be receiving any updates. It is here for historical purposes.** --- [](https://circleci.com/gh/ipfs/docs) [](https://protocol.ai/) [](http://ipfs.io/) This repository organizes overall documentation issues across the IPFS project. It's also home to the codebase for the **legacy** IPFS documentation site (available at [docs.ipfs.io](https://docs.ipfs.io/)). **The code for the current (beta) version of IPFS documentation is available at [github.com/ipfs/ipfs-docs-v2](https://github.com/ipfs/ipfs-docs-v2), and all work on IPFS docs features OR content should be done there.** Once we fully deprecate the legacy site, we'll move the beta codebase into this repo. - [Join our monthly sync](#join-our-monthly-sync) - [Get involved](#get-involved) - [Project organization](#project-organization) - [Objectives for 2020 Q1](#objectives-for-2020-q1) - [IPFS docs core members](#ipfs-docs-core-members) - [Suggestions](#suggestions) - [Bounties](#bounties) - [Legacy code details](#legacy-code-details) - [License](#license) ## Join our monthly sync Every month the team gets together to discuss plans for the coming four-ish weeks. This meeting usually happens on the last Tuesday of each month. Feel free to [join us](https://protocol.zoom.us/j/614386160) using `614386160` as the Zoom meeting ID! Here are the details for the next meeting: | Date | Time | Zoom ID | Link | Notes | | ---- | ---- | ------- | ---- | ----- | | Tuesday 26th May 2020 | UTC: 16:00 - 16:30EST: 11:00 - 11:30PST 08:00-08:30Unix: 1590508800 | `92681067428` | [protocol.zoom.us/j/92681067428](https://protocol.zoom.us/j/92681067428) | [Meeting notes](https://www.google.com/url?q=https://docs.google.com/document/d/1EOD-pJi4GvRmGi9HHocgVV8uVHMFIZlyVgJDkvC3DQ4/edit&sa=D&ust=1563045367944000&usg=AOvVaw1PXuFUmNdcfz8M0oJjv1dP) | If you can't make the meeting, don't worry. We post a recording of each meeting in our [YouTube playlist](https://www.youtube.com/playlist?list=PLuhRWgmPaHtRnfsVYI2LbVS03BRX7TcXq). Notes from current and past calls can be found [here](https://www.google.com/url?q=https://docs.google.com/document/d/1EOD-pJi4GvRmGi9HHocgVV8uVHMFIZlyVgJDkvC3DQ4/edit&sa=D&ust=1563045367944000&usg=AOvVaw1PXuFUmNdcfz8M0oJjv1dP). ## Get involved We would **love ❤️ your help** to improve existing items or make new ones even better! [We also have bounties available!](https://github.com/ipfs/devgrants/projects/1) Here are some ideas to get you started: 1. **Join us on our weekly call!** See the top of this readme for full details on how and when. 2. **Claim an issue labeled "help wanted" in either [this docs repo](https://github.com/ipfs/docs/labels/help%20wanted) or [the IPFS website repo](https://github.com/ipfs/website/labels/help%20wanted)!** All our issues are T-shirt sized and roughly difficulty-graded (both using labels), so have a look for something that interests you in the time you have available, and dive on in! Leave your thoughts and questions in issue comments, and we'll get back to you as soon as possible. 3. **Create (or improve) an example, tutorial or concept guide!** At present, we have a variety of how-tos and concept guides available at [docs-beta.ipfs.io](https://docs-beta.ipfs.io). However, every new item we can offer makes it easier for the world's community to use and build on IPFS. If you'd like to write a new example/tutorial or concept guide, [take a look in our open issues](https://github.com/ipfs/docs/issues?q=is%3Aissue+is%3Aopen+label%3A%22Category%3A+Content%22) for items with the `Category: Content` label and see if any already-identified needs appeal to you. **Note that some issues may have bounties!** If you'd like to write something entirely new, feel free — PRs are welcome! Or, if you'd just like to improve existing docs content, feel free to fork it and add your suggestions. 4. **Help us improve how we present reference and API documentation.** In Q2 2020, we're investigating the best way to improve how we present reference materials like API documentation and command-line dictionaries. Got thoughts? [Please discuss them!](https://github.com/ipfs/docs/issues/393) If you're able to contribute to any of the categories above, we thank you in advance -- your work directly improves the future of IPFS for the global community! Before posting a PR with your changes, please be sure to check [our documentation style guide](https://github.com/ipfs/community/blob/master/DOCS_STYLEGUIDE.md) and the overall [IPFS contributor guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) so we can ensure that docs are clear, consistent, and simple to read. Finally, please make sure to follow the [IPFS code of conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). ### Issues If you find something wrong within this repository, please raise an [issue here](https://github.com/ipfs/docs/issues). #### IPFS Docs beta Issues regarding the new IPFS Docs beta website should be raised in [this repository's issue tracker](https://github.com/ipfs/docs/issues). The **Issues** tab has been disabled in the `ipfs/ipfs-docs-v2` repository to stop issues being posted there. The content of `ipfs/ipfs-docs-v2` will be merged with the content of this repository in quarter 2 of 2020. We could completely delete the `ipfs/docs` repository and replace it with `ipfs/ipfs-docs-v2`. However, we still want to be able to view the git commit history and issues previously raised within this repository. ## Project organization ### Objectives for 2020 Q1 Here's a summary of this our objectives for the first three months of 2020: 1. ✅ Launch the [beta IPFS documentation](https://docs-beta.ipfs.io/) site on the IPFS network. 2. Improve documentation by creating new and/or enhancing existing content based on [issues in this repo](https://github.com/ipfs/docs/issues). 3. Resolving or addressing any new GitHub issues created in this repo this quarter. 4. Setting up and enabling a community of writers and content creators. For more information regarding these objectives, check out the [IPFS-wide Objectives and Key Results (OKRs) tracking document](https://docs.google.com/spreadsheets/d/1vOSCIufWfU2CpG63rOTGVQ6tWNYcbnYvR2k_kN84jQU/edit#gid=1562851442). ## Suggestions Do you have suggestions on future improvements to IPFS docs? You can [vote](https://ipfs.canny.io/docs-features) on what you think the IPFS docs site should contain, along with features that you'd like to see over at [canny.io/docs-features](https://ipfs.canny.io/docs-features). ### IPFS docs core members - [@johnnymatthews](https://github.com/johnnymatthews): Project leadership, organization and primary contact - [@cwaring](https://github.com/cwaring): Development support ## Bounties You can earn the undying love of the IPFS community *and* make some money by closing an issue with the [`bounty` tag](https://github.com/ipfs/docs/issues?q=is%3Aopen+is%3Aissue+label%3Abounty)! Submissions must be production-ready and meet all the specifications listed on the issue page. Check out the [current list of open bounties →](https://github.com/ipfs/devgrants/projects/1) ## Legacy code details **IMPORTANT! As noted above, this repo is home to the LEGACY docs site; if you want to make changes to IPFS docs, please visit [github.com/ipfs/ipfs-docs-v2](https://github.com/ipfs/ipfs-docs-v2) and use the codebase there.** However, if for some reason you need to run the legacy code locally, instructions are below. ### One-time setup 1. Install [AEgir](https://www.npmjs.com/package/aegir) ```sh npm install aegir ``` 2. Download dependencies and IPFS libraries (e.g., go-ipfs, js-ipfs) and generate their documentation: ```sh make install ``` This installs dependencies and generates source files from other projects (e.g., API documentation, theme resources from the `ipfs-css`, etc). When dependencies or external packages (like `go-ipfs`) have new releases, you should regenerate files based on them by running `make resources`. ### Build and run 1. In the root directory, run `make dev`. 2. Load [localhost:1313](http://localhost:1313) in your web browser. 3. Edit and add things! To create a production build, run `make build` instead. You'll find the final static site in the `public` directory. ## License All software code is copyright (c) Protocol Labs, Inc. under the **MIT license**. Other written documentation and content is copyright (c) Protocol Labs, Inc. under the [**Creative Commons Attribution-Share-Alike License**](https://creativecommons.org/licenses/by/4.0/). See [LICENSE file](./LICENSE) for details. --- ## File: content/community/contribute/_index.md --- title: "Get Involved" headless: true opened: true beta_equivalent: project/contribute --- --- ## File: content/community/contribute/how-to-help.md --- title: "Ways to contribute" menu: community: parent: contribute weight: 1 beta_equivalent: project/contribute --- So you want to contribute to IPFS and the ecosystem? Here is a quick listing of things we need help with and how you can get started. Even if what you want to do is not listed here, we probably accept contributions for it! If you're unsure, please open a issue. - [Code](#code) - [Documentation](#documentation) - [Support](#support) - [Testing](#testing) - [Design](#design) - [Issues / Triaging](#issues--triaging) - [Community](#community) - [Applications](#applications) - [Protocol Design](#protocol-design) - [Research](#research) ## Code IPFS and its sister-projects are big, with lots of code written in multiple languages. We always need help writing and maintaining code, but it can be daunting to just jump in. We use the label _Help Wanted_ on features or bugfixes that people can help out with. They are an excellent place for you to start contributing code. The biggest and most active repositories we have today are: - [ipfs/go-ipfs](https://github.com/ipfs/go-ipfs) - [ipfs/js-ipfs](https://github.com/ipfs/js-ipfs) - [libp2p/go-libp2p](https://github.com/libp2p/go-libp2p) - [libp2p/js-libp2p](https://github.com/libp2p/js-libp2p) If you want to start contributing to the core of IPFS, those repositories are a great place start. But the _Help Wanted_ label exists in all of our repositories across the Github organizations: - [IPFS](https://github.com/ipfs) - [libp2p](https://github.com/libp2p) - [IPLD](https://github.com/libp2p) - [Multiformats](https://github.com/multiformats) ## Documentation Again, IPFS is a huge project and undertaking. With lots of code comes the need for lots of good documentation! However, we need a lot more help to write the awesome docs the project needs. If writing technical documentation is your area, we’d absolutely love your help! The best place to get started is by looking through the [Github issues](https://github.com/ipfs/docs) within this repository. ## Support IPFS already has lots of users and curious people experimenting and using IPFS in their applications. These users sometimes get stuck or have questions that need answering. If you’ve contributed something with code or documentation, chances are that you can probably help a lot of people with their questions. The [IPFS forum](https://discuss.ipfs.io/) is the best place to go if you're looking for support. ## Testing We’re continuously improving IPFS every day, but mistakes can happen and we could release something that doesn’t work as well as it should — or simply doesn't work at all! If you like to dig into edge-cases or write testing scenarios, wrangling our testing infrastructure could be the job for you. We work on [CI tools](https://github.com/ipfs/jenkins) and plan larger scale tests at [ipfs/kubernetes-ipfs](https://github.com/ipfs/kubernetes-ipfs). ## Design We have many design needs, but only a small team of visual and UX designers who divide their time between IPFS-related projects and other work here. That means there are a number of issues which could use your design contributions. As home to IPFS Desktop and Companion, the [ipfs-gui](https://github.com/ipfs/ipfs-gui) repo is a good place to look for opportunities to help move our design work forward. Simply filter by the label that best fits your skillset, such as [design-visual](https://github.com/ipfs/ipfs-gui/issues?q=is%3Aissue+is%3Aopen+label%3Adesign-visual) or [design-ux](https://github.com/ipfs/ipfs-gui/labels/design-ux). ## Issues / Triaging With lots of code come lots of Github Issues. We need YOU to help with organizing all of this in some manner. We don’t yet have any proper resources for getting started with this. Get in touch if you can contribute a sense of extreme organization! We currently don't have a single place for this. If you'd like to start it, please let us know. ## Community If interacting with people is your favorite thing to do in this world, IPFS and co. are always happy to help you organize events and/or workshops to teach IPFS. We have a [repository for organizing community events](https://github.com/ipfs/community) and would love your help to have meetups in more locations or make the existing ones more regular. ## Applications IPFS is designed for others to build applications around it! Building applications and services using IPFS is an excellent way to find use cases where IPFS doesn’t yet do a perfect job or uncover bugs and inefficiencies. Get started by looking at our awesome-ipfs list. Build anything you think is missing! If you're unsure about something, please create an issue to get help or feedback on your specific problem/idea. - [ipfs/awesome-ipfs](https://github.com/ipfs/awesome-ipfs) - [ipfs/notes](https://github.com/ipfs/notes) - [ipfs/apps](https://github.com/ipfs/apps) - [IPFS forum](https://discuss.ipfs.io/) ## Protocol Design IPFS is ultimately about building better protocols, and we always welcome ideas and feedback on how to improve those protocols. Post feedback, issues, and proposals in the `specs` projects in our Github organizations or in [`ipfs/notes`](https://github.com/notes). - [ipfs/specs](https://github.com/ipfs/specs) - [libp2p/specs](https://github.com/libp2p/specs) - [ipld/specs](https://github.com/ipld/specs) - [multiformats/specs](https://github.com/multiformats/specs) - [ipfs/notes](https://github.com/ipfs/notes) ## Research Finally, we see Protocol Labs as a research lab, where YOUR ideas can become technologies that have a real impact on the world. If you're interested in contributing to our research, please reach out to [mailto:research@ipfs.io](research@ipfs.io) or [research@protocol.ai](mailto:research@protocol.ai) for more information. Include what your interests are so we can make sure you get to work on something fun and valuable. --- ## File: content/community/_index.md --- title: "Community" headless: true opened: true beta_equivalent: community --- The IPFS community is as decentralized and distributed as IPFS itself. Our community members are globally located, active both online and in person, and use IPFS in countless different ways. You can learn about meetings, events, apps people are building, and more with the resources listed here. ## Discussion/Support Forum Join the conversation on the [IPFS Forums](https://discuss.ipfs.io/) for everything from technical questions, project brainstorming, talk on IPFS use cases and more. ## Research Discussion The [IPFS Collaborative Notebook for Research](https://github.com/ipfs/notes) repo tracks discussions on topics related to IPFS research, ideas and proposals for new systems/features, and other items that haven't yet been tracked into a specific project. ## Events Calendar Find all of the open community video calls for the IPFS project in the [IPFS Community events calendar](https://calendar.google.com/calendar/embed?src=ipfs.io_eal36ugu5e75s207gfjcu0ae84@group.calendar.google.com). ## Community Tools Join the discussion and documentation on IPFS community practices in the [community tools repo](https://github.com/ipfs/community/). If you want to start or get involved with a community chapter to help expand IPFS awareness in your local geographical or online community, here's where to look. ## Project Management Keep abreast of IPFS team planning, management and coordination issues in the [IPFS team management repo](https://github.com/ipfs/team-mgmt). ## Blog Explore the latest news, events and other happenings in the IPFS multiverse on the official [IPFS Blog](https://blog.ipfs.io/). ## IPFS YouTube channel The [IPFS YouTube channel](https://www.youtube.com/channel/UCdjsUXJ3QawK4O5L1kqqsew) is home to a wealth of information about the IPFS project — everything from IPFS Camp course content to working group meeting archives — so you can explore playlists and subscribe to ones that interest and inform you. ## Twitter Get your IPFS news in tweet-sized bites. Follow these accounts for the latest: - [@IPFSbot](https://twitter.com/IPFSbot) for news and other updates - [@IPFSevents](https://twitter.com/ipfsevents) for info on IPFS-related events - [@ProtoSchool](https://twitter.com/protoschool) for updates on [ProtoSchool](https://proto.school) tutorials and events ## Community projects on Awesome IPFS Get inspired by [Awesome IPFS](https://awesome.ipfs.io/), a catalog of community-built projects using IPFS for everything from image sharing to decentralized archiving. Have a project of your own to add to Awesome IPFS? [Make a PR](https://github.com/ipfs/awesome-ipfs) in the repo! ## Public archives on IPFS Curious about what public datasets are available on IPFS for you to play with? There's a [section on Awesome IPFS](https://awesome.ipfs.io/datasets/) dedicated to just that. ## Forum FAQ Archive We're in the midst of migrating frequently-asked questions from the IPFS forum archives into our primary [FAQ](/introduction/faq/), but in the meantime, you can find them [in the forums](https://discuss.ipfs.io/c/help/Old-FAQ). --- ## File: content/community/irc.md --- title: "IRC" beta_equivalent: community/irc --- There are several IRC channels on Freenode dedicated to IPFS, and it’s a great place for live chat: - Use [#ipfs on irc.freenode.org](irc://irc.freenode.org/%23ipfs) for general IPFS usage and community chat. - Use [#ipfs-dev on irc.freenode.org](irc://irc.freenode.org/%23ipfs-dev) for discussing implementation details, especially if you are contributing code to IPFS. For longer-lived discussions and for support, please use the discussion forums at https://discuss.ipfs.io instead of IRC! It’s easy for complex discussions to get lost in a sea of new messages on IRC. --- If you’re new to IRC, there are *lots* of mobile and desktop clients for working with it. Here are a few to get you started: - [IRCCloud][irccloud] on the web and desktop - [Textual][textual] or [Adium][adium] on macOS - [mIRC][mirc] or [HexChat][hexchat] on Windows - [XChat][xchat] or [Irssi][irssi] on Linux [adium]: https://adium.im [hexchat]: https://hexchat.github.io [irccloud]: https://irccloud.com [irssi]: https://irssi.org [mirc]: http://standaloneinstaller.com/download-mirc [textual]: https://www.codeux.com/textual/ [xchat]: http://xchat.org --- ## File: content/guides/concepts/_index.md --- title: "Concepts" menu: guides: identifier: concepts weight: 2 beta_equivalent: essentials --- --- ## File: content/guides/concepts/cid.md --- title: "Content Identifiers (CIDs)" menu: guides: parent: concepts beta_equivalent: concepts/content-addressing --- A *content identifier*, or CID, is a label used to point to material in IPFS. It doesn't indicate _where_ the content is stored, but it forms a kind of address based on the content itself. CIDs are short, regardless of the size of their underlying content. CIDs are based on the content’s [cryptographic hash]({{< relref "./hashes.md" >}}). That means: * Any difference in content should produce a different CID and * The same piece of content added to two different IPFS nodes using the same settings should produce _exactly the same CID_. ## CID formats CIDs can take a few different forms with different encoding bases or CID versions. Many of the existing IPFS tools still generate v0 CIDs, although the `files` ([MFS]({{< relref "./mfs.md" >}})) and `object` operations now use CIDv1 by default. ### Version 0 When IPFS was first designed, we used base 58-encoded multihashes as the content identifiers (This is simpler, but much less flexible than newer CIDs). CIDv0 is still used by default for many IPFS operations, so you should generally try to support v0. If a CID is 46 characters starting with "Qm", it's a CIDv0 (for more details, check the [decoding algorithm](https://github.com/ipld/cid/blob/ef1b2002394b15b1e6c26c30545fd485f2c4c138/README.md#decoding-algorithm) in the CID specification). ### Version 1 CID v1 contains some leading identifiers that clarify exactly which representation is used, along with the content-hash itself. These include: * A [multibase](https://github.com/multiformats/multibase) prefix, specifying the encoding used for the remainder of the CID * A CID version identifier, which indicates which version of CID this is * A [multicodec](https://github.com/multiformats/multicodec) identifier, indicating the format of the target content — it helps people and software to know how to interpret that content after the content is fetched These leading identifiers also provide forward-compatibility, supporting different formats to be used in future versions of CID. You can use the first few bytes of the CID to interpret the remainder of the content address and know how to decode the content after it's fetched from IPFS. For more details, check out the [CID specification](https://github.com/ipld/cid). It includes a [decoding algorithm](https://github.com/ipld/cid/blob/ef1b2002394b15b1e6c26c30545fd485f2c4c138/README.md#decoding-algorithm) and links to existing software implementations for decoding CIDs. ## Explore CIDs for yourself Want to pull apart a specific CID's multibase, multicodec, or multihash info? You can use the [CID Inspector](https://cid.ipfs.io/#QmY7Yh4UquoXHLPFo2XbhXkhBvFoPwmQUSa92pxnxjQuPU) or the [CID Info panel in IPLD Explorer](https://explore.ipld.io/#/explore/QmY7Yh4UquoXHLPFo2XbhXkhBvFoPwmQUSa92pxnxjQuPU) (both links launch using a sample CID) for an interactive breakdown of differently-formatted CIDs. Also learn about [the future of CIDs in IPFS](https://discuss.ipfs.io/t/who-decides-what-hashing-algorithms-ipfs-allows/6742). --- ## File: content/guides/concepts/dht.md --- title: "Distributed Hash Tables (DHT)" menu: guides: parent: concepts beta_equivalent: concepts/dht --- # DHTs ## What is a DHT? [Distributed Hash Tables](https://en.wikipedia.org/wiki/Distributed_hash_table) (DHTs) are distributed key-value stores where keys are [cryptographic hashes](https://docs.ipfs.io/guides/concepts/hashes/). DHTs are distributed. Each "peer" (or "node") is responsible for a subset of the DHT. When a peer receives a request, it either answers it, or the request is passed to another peer until a peer that can answer it is found. Depending on the implementation, a request not answered by the first node contacted can be: - forwarded from peer to peer, with the last peer contacting the requesting peer - forwarded from peer to peer, with the answer forwarded following the same path - answered with the contact information of a node that has better chances to be able to answer. **IPFS uses this strategy.** DHTs' decentralization provides advantages compared to a traditional key-value store, including: - *scalability*, since a request for a hash of length *n* takes at most *log2(n)* steps to resolve. - *fault tolerance* via redundancy, so that lookups are possible even if peers unexpectedly leave or join the DHT. Additionally, requests can be addressed to any peer if another peer is slow or unavailable. - *load balancing*, since requests are made to different nodes and no unique peers process all the requests. ## How does the IPFS DHT work? ### Peer IDs Each peer has a `peerID`, which is a hash with the same length *n* as the DHT keys. ### Buckets A subset of the DHT maintained by a peer is called a 'bucket'. A bucket maps to hashes with the same prefix as the `peerID`, up to *m* bits. There are 2^m buckets. Each bucket maps for 2^(n-m) hashes. For example, if *m*=16 and we use hexadecimal encoding (four bits per displayed character), the peer with `peerID` 'ABCDEF12345' maintains mapping for hashes starting with 'ABCD'. Some hashes falling into this bucket would be *ABCD*38E56, *ABCD*09CBA or *ABCD*17ABB, just as examples. The size of a bucket is related to the size of the prefix. The longer the prefix, the fewer hashes each peer has to manage, and the more peers are needed. Several peers can be in charge of the same bucket if they have the same prefix. In most DHTs, including [IPFS's Kademlia implementation](https://github.com/libp2p/specs/blob/8b89dc2521b48bf6edab7c93e8129156a7f5f02c/kad-dht/README.md), the size of the buckets (and the size of the prefix), are dynamic. ### Peer lists Peers also keep a connection to other peers in order to forward requests if the requested hash is not in their own bucket. If hashes are of length n, a peer will keep n-1 lists of peers: - the first list contains peers whose IDs have a different first bit. - the second list contains peers whose IDs have first bits identical to its own, but a different second bit - ... - the m-th list contains peers whose IDs have their first m-1 bits identical, but a different m-th bit - ... The higher m is, the harder it is to find peers that have the same ID up to m bits. The lists of "closest" peers typically remains empty. "Close" here is defined as the XOR distance, so the longer the prefix they share, the closer they are. Lists also have a maximum of entries (k) — otherwise the first lists would contain half the network, then a fourth of the network, and so on. ### Using the DHT When a peer receives a lookup request, it will either answer with a value if it falls into its own bucket, or answer with the contacting information (IP+port, `peerID`, etc.) of a closer peer. The requesting peer can then send its request to this closer peer. The process goes on until a peer is able to answer it. A request for a hash of length n will take at maximum log2(n) steps, or even log2m(n). ### Keys and hashes In IPFS's Kademlia DHT, keys are SHA256 hashes. [PeerIDs](https://docs.libp2p.io/concepts/peer-id/) are those of [libp2p](https://libp2p.io/), the networking library used by IPFS. We use the DHT to look up two types of objects, both represented by SHA256 hashes: - [Content IDs](https://docs.ipfs.io/guides/concepts/cid/) of the data added to IPFS. A lookup of this value will give the `peerID`s of the peers having this immutable content. - [IPNS records](https://docs.ipfs.io/guides/concepts/ipns/). A lookup will give the last Content ID associated with this IPNS address, enabling the routing of mutable content. Consequently, IPFS's DHT is one of the ways to achieve mutable and immutable [content routing](https://docs.libp2p.io/concepts/content-routing/). It's currently the only one [implemented](https://libp2p.io/implementations/#peer-routing). You can learn more in the [libp2p Kademlia DHT specification](https://github.com/libp2p/specs/blob/8b89dc2521b48bf6edab7c93e8129156a7f5f02c/kad-dht/README.md). ## Usage ### Adding an entry Adding a blob of data to IPFS is the equivalent of advertising that you have it. Since DHT is the only content routing implemented, you can just use: ` ipfs add myData` IPFS will automatically chunk your data and add a mapping on the DHT between the Content ID and your `peerID`. Note that there can be other `peerID`s already mapped to that value, so you will be added to the list. Also note that if the provided data is bigger than 124KB, it will be chunked into "blocks", and both those blocks and the overall data will be mapped. You can publish an IPNS record using [`ipfs.name.publish`](https://docs.ipfs.io/guides/concepts/ipns/). --- ## File: content/guides/concepts/dnslink.md --- title: "DNSLink" menu: guides: parent: concepts beta_equivalent: concepts/dnslink --- **NOTE: The info below is a quick guide to DNSLink. For a more complete guide, including tutorials, usage examples and FAQs, check out [dnslink.io](http://dnslink.io/).** ## What is DNSLink? DNSLink uses [DNS TXT](https://en.wikipedia.org/wiki/TXT_record) records to map a domain name (like `ipfs.io`) to an IPFS address. Because you can edit your DNS records, you can use them to always point to the latest version of an object in IPFS (remember that an IPFS object’s address changes if you modify the object). Since DNSLink uses DNS records, you can assign names/paths/(sub)domains/whatever that are easy to type, read, and remember. A DNSLink address looks like an [IPNS](/guides/concepts/ipns) address, but it uses a domain name in place of a hashed public key: ``` /ipns/myexampledomain.org ``` Just like normal IPFS addresses, they can include links to other files — or other types of resources that IPFS supports, like directories and symlinks: ``` /ipns/myexampledomain.org/media/ ``` ### Publishing using a subdomain While you can publish the TXT record to the exact domain if you so wish, it can be more advantageous to publish DNSLink records using a special subdomain called `_dnslink`. This enables you to improve the security of an automated setup, or delegate control over your DNSLink records to a third party without giving away full control over the original DNS zone. For example, [`docs.ipfs.io`](https://docs.ipfs.io) does not have a TXT record, but the page still loads because a TXT record exists for `_dnslink.docs.ipfs.io`. If you look up the DNS records for `_dnslink.docs.ipfs.io`, you'll see its DNSLink entry: ```sh $ dig +noall +answer TXT _dnslink.docs.ipfs.io _dnslink.docs.ipfs.io. 34 IN TXT "dnslink=/ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya" ``` ### Resolving using DNSLink When an IPFS client or node attempts to resolve an address, it looks for a `TXT` record that is prefixed with `dnslink=`. The rest can be an `/ipfs/` link (as in the example below), or `/ipns/`, or even a link to another DNSLink. ``` dnslink=/ipfs/ ``` For example, let's go back to when we looked up the DNS records for `_dnslink.docs.ipfs.io` and saw its DNSLink entry: ```sh $ dig +noall +answer TXT _dnslink.docs.ipfs.io _dnslink.docs.ipfs.io. 34 IN TXT "dnslink=/ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya" ``` Based on that, this address: ``` /ipns/docs.ipfs.io/introduction/ ``` Will get you this block: ``` /ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya/introduction/ ``` --- ## File: content/guides/concepts/hashes.md --- title: "Hashes" menu: guides: parent: concepts beta_equivalent: concepts/hashing --- Hashes are functions that take some arbitrary input and return a fixed-length value. The particular value depends on the given hash algorithm in use, such as [SHA-1](https://en.wikipedia.org/wiki/SHA-1) (used by Git), [SHA-256](https://en.wikipedia.org/wiki/SHA-2), or [BLAKE2](https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2), but a given hash algorithm always returns the same value for a given input. Have a look at the [full list of hash functions](https://en.wikipedia.org/wiki/List_of_hash_functions) for more. As an example, the input: ``` Hello world ``` would be represented by **SHA-1** as: ``` 0x7B502C3A1F48C8609AE212CDFB639DEE39673F5E ``` However, the exact same input generates the following output using **SHA-256**: ``` 0x64EC88CA00B268E5BA1A35678A1B5316D212F4F366B2477232534A8AECA37F3C ``` Notice that the second hash is longer than the first one. This is because SHA-1 creates a 160 bit hash, while SHA-256 creates a 256 bit hash. Also, the prepended `0x` is just an indicator that tells us that the following hash is represented as a base 16 (or hexadecimal) number. Hashes can be represented in different bases (`base2`, `base16`, `base32`, etc.). In fact, IPFS makes use of that as part of its [Content Identifiers]({{< relref "cid.md" >}}) and supports mulitiple base representations at the same time, using the [Multibase](https://github.com/multiformats/multibase) protocol. For example, the SHA-256 hash of "Hello World" from above can be represented as base 32 as: ``` mtwirsqawjuoloq2gvtyug2tc3jbf5htm2zeo4rsknfiv3fdp46a ``` ## Characteristics of cryptographic hashes Cryptographic hashes come with a couple of very important characteristics: - **deterministic** - the same input message always returns exactly the same output hash - **uncorrelated** - a small change in the message should generate a completely different hash - **unique** - it's infeasible to generate the same hash from two different messages - **one-way** - it's infeasible to guess or calculate the input message from its hash It turns out these features also mean we can use a cryptographic hash to identify any piece of data: the hash is unique to the data we calculated it from and it’s not too long (a hash is a fixed length, so the SHA-256 hash of a 1 Gigabyte video file is still only 32 bytes), so sending it around the network doesn't take up a lot of resources. That's critical for a distributed system like IPFS, where we want to be able to store and retrieve data from many places. A computer running IPFS can ask all the peers it's connected to whether they have a file with a particular hash and, if one of them does, they send back the whole file. Without a short, unique identifier like a cryptographic hash, that wouldn't be possible. This technique is called “content addressing” — because the content itself is used to form an address, rather than information about the computer and disk location it's stored at.