3. Getting started¶
The first thing to do is to start up your Swarm node and connect it to the Swarm.
3.1. Running Swarm¶
To start a basic Swarm node you must have both
swarm installed on your machine. You can find the relevant instructions in the Installation and Updates section.
To start Swarm you need an Ethereum account. You can create a new account by running the following command:
geth account new
You will be prompted for a password:
Your new account is locked with a password. Please give a password. Do not forget this password. Passphrase: Repeat passphrase:
Once you have specified the password, the output will be the Ethereum address representing that account. For example:
Using this account, connect to Swarm with
swarm --bzzaccount <your-account-here> # in our example swarm --bzzaccount 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1
(You should replace 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1 with your address).
3.2. How do I enable ENS name resolution?¶
ENS is based on a suite of smart contracts running on the Ethereum mainnet.
The Ethereum Name Service is the Ethereum equivalent of DNS in the classic web. In order to use ENS to resolve names to swarm content hashes,
swarm has to connect to a
geth instance that is connected to the Ethereum mainnet. This is done using the
First you must start your geth node and establish connection with Ethereum main network with the following command:
for a full geth node, or
for light client mode.
When you use the light mode, you don’t have to sync the node before it can be used to answer ENS queries. However, please note that light mode is still an experimental feature.
After the connection is established, open another terminal window and connect to Swarm:
swarm --ens-api '$HOME/.ethereum/geth.ipc' \ --bzzaccount 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1
For Mac OS, replace “$HOME/.ethereum/” with “~/Library/Ethereum/”
Verify that this was successful by pointing your browser to http://localhost:8500/bzz:/theswarm.eth/
3.2.1. Using Swarm together with the testnet ENS¶
It is also possible to use the Ropsten ENS test registrar for name resolution instead of the Ethereum main .eth ENS on mainnet.
Run a geth node connected to the Ropsten testnet
Then launch the swarm; connecting it to the geth node (
swarm --ens-api $HOME/.ethereum/geth/testnet/geth.ipc
Swarm will automatically use the ENS deployed on Ropsten.
For other ethereum blockchains and other deployments of the ENS contracts, you can specify the contract addresses manually. For example the following command:
swarm --ens-api eth:314159265dD8dbb310642f98f50C066173C1259b@/home/user/.ethereum/geth.ipc \ --ens-api test:0x112234455C3a32FD11230C42E7Bccd4A84e02010@ws:188.8.131.52:5678 \ --ens-api 0x230C42E7Bccd4A84e02010112234455C3a32FD11@ws:184.108.40.206:2345
Will use the
geth.ipc to resolve
.eth names using the contract at
314159265dD8dbb310642f98f50C066173C1259b and it will use
ws:220.127.116.11:5678 to resolve
.test names using the contract at
0x112234455C3a32FD11230C42E7Bccd4A84e02010. For all other names it will use the ENS contract at
3.2.2. Using an external ENS source¶
Take care when using external sources of information. By doing so you are trusting someone else to be truthful. Using an external ENS source may make you vulnerable to man-in-the-middle attacks. It is only recommended for test and development environments.
Maintaining a fully synced Ethereum node comes with certain hardware and bandwidth constraints, and can be tricky to achieve. Also, light client mode, where syncing is not necessary, is still experimental.
An alternative solution for development purposes is to connect to an external node that you trust, and that offers the necessary functionality through http.
If the external node is running on IP 18.104.22.168 port 8545, the command would be:
swarm --ens-api http://22.214.171.124:8545
You can also use
https. But keep in mind that Swarm does not validate the certificate.
3.3. Alternative modes¶
Below are examples on ways to run swarm beyond just the default network.
3.3.1. Swarm in singleton mode (no peers)¶
To launch in singleton mode, use the
--maxpeers 0 flag.
swarm --bzzaccount $BZZKEY \ --datadir $DATADIR \ --ens-api $DATADIR/geth.ipc \ --maxpeers 0
3.3.2. Adding enodes manually¶
By default, swarm will automatically seek out peers in the network. This can be suppressed using the
swarm --bzzaccount $BZZKEY \ --datadir $DATADIR \ --ens-api $DATADIR/geth.ipc \ --nodiscover
Without discovery, it is possible to manually start off the connection process by adding one or more peers using the
admin.addPeer console command.
geth --exec='admin.addPeer("ENODE")' attach ipc:/path/to/bzzd.ipc
When you stop a node, all peer connections will be saved. When you start again, the node will try to reconnect to those peers automatically.
Where ENODE is the enode record of a swarm node. Such a record looks like the following:
The enode of your swarm node can be accessed using
geth connected to
geth --exec "admin.nodeInfo.enode" attach ipc:/path/to/bzzd.ipc
geth is used for two different purposes here: You use it to run an Ethereum Mainnet node for ENS lookups. But you also use it to “attach” to the Swarm node to send commands to it.
3.3.3. Connecting to the public Swarm cluster¶
If you would like to join the public Swarm cluster operated by the Ethereum Foundation and other contributors, you can use one of the bootnodes avaible from this list:
The cluster functions as a free-to-use public access gateway to Swarm, without the need to run a local node. To download data through the gateway use the