mirror of
https://github.com/ipfs/kubo.git
synced 2026-02-21 10:27:46 +08:00
25ebab9dae
* feat(p2p): add --foreground flag to listen and forward commands
adds `-f/--foreground` option that keeps the command running until
interrupted (SIGTERM/Ctrl+C) or closed via `ipfs p2p close`. the
listener/forwarder is automatically removed when the command exits.
useful for systemd services and scripts that need cleanup on exit.
* docs: add p2p-tunnels.md with systemd examples
- add dedicated docs/p2p-tunnels.md covering:
- why p2p tunnels (NAT traversal, no public IP needed)
- quick start with netcat
- background and foreground modes
- systemd integration with path-based activation
- security considerations and troubleshooting
- document Experimental.Libp2pStreamMounting in docs/config.md
- simplify docs/experimental-features.md, link to new doc
- add "Learn more" links to ipfs p2p listen/forward --help
- update changelog entry with doc link
- add cross-reference in misc/README.md
* chore: reference kubo#5460 for p2p config
Ref. https://github.com/ipfs/kubo/issues/5460
* fix(daemon): write api/gateway files only after HTTP server is ready
fixes race condition where $IPFS_PATH/api and $IPFS_PATH/gateway files
were written before the HTTP servers were ready to accept connections.
this caused issues for tools like systemd path units that immediately
try to connect when these files appear.
changes:
- add corehttp.ServeWithReady() that signals when server is ready
- wait for ready signal before writing address files
- use sync.WaitGroup.Go() (Go 1.25) for cleaner goroutine management
- add TestAddressFileReady to verify both api and gateway files
* fix(daemon): buffer errc channel and wait for all listeners
- buffer error channel with len(listeners) to prevent deadlock when
multiple servers write errors simultaneously
- wait for ALL listeners to be ready before writing api/gateway file,
not just the first one
Feedback-from: https://github.com/ipfs/kubo/pull/11099#pullrequestreview-3593885839
* docs(changelog): improve p2p tunnel section clarity
reframe to lead with user benefit and add example output
* docs(p2p): remove obsolete race condition caveat
the "First launch fails but restarts work" troubleshooting section
described a race where the api file was written before the daemon was
ready. this was fixed in 80b703a which ensures api/gateway files are
only written after HTTP servers are ready to accept connections.
---------
Co-authored-by: Andrew Gillis <11790789+gammazero@users.noreply.github.com>
132 lines
4.0 KiB
Markdown
132 lines
4.0 KiB
Markdown
## init system integration
|
|
|
|
go-ipfs can be started by your operating system's native init system.
|
|
|
|
- [systemd](#systemd)
|
|
- [LSB init script](#initd)
|
|
- [Upstart/startup job](#upstart)
|
|
- [launchd](#launchd)
|
|
|
|
### systemd
|
|
|
|
For `systemd`, the best approach is to run the daemon in a user session. Here is a sample service file:
|
|
|
|
```systemd
|
|
[Unit]
|
|
Description=IPFS daemon
|
|
|
|
[Service]
|
|
# Environment="IPFS_PATH=/data/ipfs" # optional path to ipfs init directory if not default ($HOME/.ipfs)
|
|
ExecStart=/usr/local/bin/ipfs daemon
|
|
Restart=on-failure
|
|
|
|
[Install]
|
|
WantedBy=default.target
|
|
```
|
|
|
|
To run this in your user session, save it as `~/.config/systemd/user/ipfs.service` (creating directories as necessary). Once you run `ipfs init` to create your IPFS settings, you can control the daemon using the following commands:
|
|
|
|
* `systemctl --user start ipfs` - start the daemon
|
|
* `systemctl --user stop ipfs` - stop the daemon
|
|
* `systemctl --user status ipfs` - get status of the daemon
|
|
* `systemctl --user enable ipfs` - enable starting the daemon at boot
|
|
* `systemctl --user disable ipfs` - disable starting the daemon at boot
|
|
|
|
*Note:* If you want this `--user` service to run at system boot, you must [`enable-linger`](http://www.freedesktop.org/software/systemd/man/loginctl.html) on the account that runs the service:
|
|
|
|
```
|
|
# loginctl enable-linger [user]
|
|
```
|
|
Read more about `--user` services here: [wiki.archlinux.org:Systemd ](https://wiki.archlinux.org/index.php/Systemd/User#Automatic_start-up_of_systemd_user_instances)
|
|
|
|
#### P2P tunnel services
|
|
|
|
For running `ipfs p2p listen` or `ipfs p2p forward` as systemd services,
|
|
see [docs/p2p-tunnels.md](../docs/p2p-tunnels.md) for examples using the
|
|
`--foreground` flag and path-based activation.
|
|
|
|
### initd
|
|
|
|
- Here is a full-featured sample service file: https://github.com/dylanPowers/ipfs-linux-service/blob/master/init.d/ipfs
|
|
- Use `service` or your distribution's equivalent to control the service.
|
|
|
|
## upstart
|
|
|
|
- And below is a very basic sample upstart job. **Note the username jbenet**.
|
|
|
|
```
|
|
cat /etc/init/ipfs.conf
|
|
```
|
|
```
|
|
description "ipfs: interplanetary filesystem"
|
|
|
|
start on (local-filesystems and net-device-up IFACE!=lo)
|
|
stop on runlevel [!2345]
|
|
|
|
limit nofile 524288 1048576
|
|
limit nproc 524288 1048576
|
|
setuid jbenet
|
|
chdir /home/jbenet
|
|
respawn
|
|
exec ipfs daemon
|
|
```
|
|
|
|
Another version is available here:
|
|
|
|
```sh
|
|
ipfs cat /ipfs/QmbYCwVeA23vz6mzAiVQhJNa2JSiRH4ebef1v2e5EkDEZS/ipfs.conf >/etc/init/ipfs.conf
|
|
```
|
|
|
|
For both, edit to replace occurrences of `jbenet` with whatever user you want it to run as:
|
|
|
|
```sh
|
|
sed -i s/jbenet/<chosen-username>/ /etc/init/ipfs.conf
|
|
```
|
|
|
|
Once you run `ipfs init` to create your IPFS settings, you can control the daemon using the `init.d` commands:
|
|
|
|
```sh
|
|
sudo service ipfs start
|
|
sudo service ipfs stop
|
|
sudo service ipfs restart
|
|
...
|
|
```
|
|
|
|
## launchd
|
|
|
|
Similar to `systemd`, on macOS you can run `go-ipfs` via a user LaunchAgent.
|
|
|
|
- Create `~/Library/LaunchAgents/io.ipfs.go-ipfs.plist`:
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
<plist version="1.0">
|
|
<dict>
|
|
<key>KeepAlive</key>
|
|
<true/>
|
|
<key>Label</key>
|
|
<string>io.ipfs.go-ipfs</string>
|
|
<key>ProcessType</key>
|
|
<string>Background</string>
|
|
<key>ProgramArguments</key>
|
|
<array>
|
|
<string>/bin/sh</string>
|
|
<string>-c</string>
|
|
<string>~/go/bin/ipfs daemon</string>
|
|
</array>
|
|
<key>RunAtLoad</key>
|
|
<true/>
|
|
</dict>
|
|
</plist>
|
|
```
|
|
The reason for running `ipfs` under a shell is to avoid needing to hard-code the user's home directory in the job.
|
|
|
|
- To start the job, run `launchctl load ~/Library/LaunchAgents/io.ipfs.go-ipfs.plist`
|
|
|
|
Notes:
|
|
|
|
- To check that the job is running, run `launchctl list | grep ipfs`.
|
|
- IPFS should now start whenever you log in (and exit when you log out).
|
|
- [LaunchControl](http://www.soma-zone.com/LaunchControl/) is a GUI tool which simplifies management of LaunchAgents.
|