diff --git a/tools/drives.md b/tools/drives.md new file mode 100644 index 0000000..c96b5e7 --- /dev/null +++ b/tools/drives.md @@ -0,0 +1,89 @@ +# Drives + +CLI to download, seed, and mirror a Hyperdrive or Localdrive. + +>[Github (drives)](https://github.com/holepunchto/drives) + +* [Installation](drives.md#installation) +* [Basic usage](drives.md#basic-usage) + +### Installation + +Install with [npm](https://www.npmjs.com/): + +```bash +npm install -g drives +``` + +### Basic usage + +```bash +drives [options] [command] +``` + +Commands: + +| Command | Options | Description | +|---------|---------|------------------------------------------| +| touch | [options] | Create a writable Hyperdrive | +| mirror | [options] | Mirror a drive into another drive | +| seed | [options] [key] | Seed a Hyperdrive to the DHT network | +| download | [options] | Download a Hyperdrive by key | +| serve | [options] | Creates a HTTP drive server | +| ls | [options] | List files of the drive | +| info | [options] [key] | Show info about the Hyperdrive | + + +#### Create a writable Hyperdrive + +``` bash +drives touch +# New drive: +``` + +#### Mirror any drive into another + +``` bash +drives mirror +``` + +> Source and destination can be a folder path or a drive key. Use `--live` for real-time mirroring, and `--verbose` to show all logs. + + +#### Share a drive + +``` bash +drives seed [my-drive-key] +``` + +#### Download a Hyperdrive + +``` bash +drives download +``` + +#### Serve a drive via HTTP + +``` bash +drives serve +# HTTP server on http://localhost:5000 +``` + +> URL requests are like `/path/to/file`, i.e., `http://localhost:5000/index.js`. + +#### List files + +``` bash +drives ls +``` + +> Currently it ignores `.git`, `.github`, `node_modules`, and `corestore` entries. + +#### Show storage size, version, etc + +``` bash +drives info [my-drive-key] +``` +--- + +> Use `drives --help` for more information, `drives mirror --help`, etc. Always add `--corestore [path]`, by default it's `./corestore`. diff --git a/tools/hyperbeam.md b/tools/hyperbeam.md new file mode 100644 index 0000000..a59d9ab --- /dev/null +++ b/tools/hyperbeam.md @@ -0,0 +1,82 @@ +# Hyperbeam + +An end-to-end encrypted pipeline for the Internet, utilizing the [hyperswarm.md](../building-blocks/hyperswarm.md "mention") and Noise Protocol for secure communications. + +> [GitHub (Hyperbeam)](https://github.com/mafintosh/hyperbeam) + +* [Installation](hyperbeam.md#installation) +* [Basic usage](hyperbeam.md#usage) +* [CLI](hyperbeam.md#cli) +* [API](hyperbeam.md#api) + +### Installation + +Install with [npm](https://www.npmjs.com/): + +```bash +npm install hyperbeam +``` + +### Basic usage + +```javascript +const Hyperbeam = require('hyperbeam') + +// to generate a passphrase, leave the constructor empty +a passphrase +const beam = new Hyperbeam() + +// Use the following constructor with ('neznr3z3j44l7q7sgynbzpdrdlpausurbpcmqvwupmuoidolbopa') a 32-byte unique passphrase +// to find the other side of the pipe. +// const beam = new Hyperbeam('neznr3z3j44l7q7sgynbzpdrdlpausurbpcmqvwupmuoidolbopa') + +// beam.key gives the passphrase +console.log('passphrase: ',beam.key) + +// make a little chat app +process.stdin.pipe(beam).pipe(process.stdout) + +``` + +### CLI + +**Step 1: Install Hyperbeam as a global npm package.** + +```bash +npm install -g hyperbeam +``` + +**Step 2: Generate a passphrase, using the following command on a machine** + +```bash +echo 'hello world' | hyperbeam +``` + +e.g. output: `neznr3z3j44l7q7sgynbzpdrdlpausurbpcmqvwupmuoidolbopa` + +**Step 3: Then on another machine run the following command** + +```bash +# will print 'hello world' +hyperbeam neznr3z3j44l7q7sgynbzpdrdlpausurbpcmqvwupmuoidolbopa +``` + +### API + +**`const stream = new Hyperbeam([key][, options])`** + +Makes a new Hyperbeam duplex stream. + +This stream will auto-connect to another peer using the same key with an end-to-end encrypted tunnel. When the other peer writes it's emitted as `data` on this stream. Likewise, writes to this stream stream are emitted as `data` on the other peer's stream. + +> If a `key` is not passed into the constructor (the passphrase), one will be generated and put on `stream.key` + +`options` include: + +| Option | Description | +| --------- | ------------------------------------------ | +| **`dht`** | A DHT instance. Defaults to a new instance | + +**`stream.key`** + +The passphrase used by the stream for connection. diff --git a/tools/hypershell.md b/tools/hypershell.md new file mode 100644 index 0000000..1755d9d --- /dev/null +++ b/tools/hypershell.md @@ -0,0 +1,116 @@ +# Hypershell + +A command-line interface for generating and connecting to peer-to-peer, end-to-end encrypted shells. + +>[GitHub (Hypershell)](https://github.com/holepunchto/hypershell) + +* [Installation](hypershell.md#installation) +* [Basic usage](hypershell.md#basic-usage) + +### Installation + +Install with [npm](https://www.npmjs.com/): + +```bash +npm install -g hypershell +``` + +### Basic usage + +**Create a P2P shell server.** + +```bash +hypershell-server [options] +``` + +`options` include: + +| Options | Description | Default | +| --------------------------- | --------------------------------- | -------------------------------- | +| **`-f `** | Filename of the server seed key. | `~/.hypershell/peer` | +| **`--firewall `** | List of allowed public keys. | `~/.hypershell/authorized_peers` | + +**Connect to a P2P shell.** + +```bash +hypershell [options] +``` + +`options` include: + +| Options | Description | Default | +| ------------------- | --------------------------------- | -------------------- | +| **`-f `** | Filename of the client seed key. | `~/.hypershell/peer` | + +**Create keys of type ed25519 for use by the holepunch-protocol.** + +```bash +hypershell-keygen [options] +``` + +`options` include: + +| Options | Description | +| ------------------- | ------------------------------ | +| **`-f `** | Filename of the seed key file. | +| **`-c `** | Provides a new comment. | + +### Setup + +First, create a key with the default filename: + +```bash +hypershell-keygen +``` + +**Client** + +Now the server can be connected to (providing the public key has been allowed): + +```bash +hypershell +``` + +**Server** + +To create a server: + +```bash +hypershell-server +``` + +`~/.hypershell/firewall` will be automatically created as an empty file. That means all connections are denied by default. + +> Public keys can be added in real time by adding them to the firewall list while `hypershell-server` is running. + +### Known peers + +There will be a file named `~/.hypershell/known_peers`. + +Add named peers to the file, for example: + +```bash +# +home cdb7b7774c3d90547ce2038b51367dc4c96c42abf7c2e794bb5eb036ec7793cd +``` + +Utilize `hypershell home` to eliminate the need for constantly providing the full public key. + +### Multiple keys + +Multiple keys are required to have multiple servers. + +Generate another key: + +```bash +hypershell-keygen -f ~/.hypershell/my-server +``` + +Create a new shell server: + + +```bash +hypershell-server -f ~/.hypershell/my-server --firewall ~/.hypershell/my-server-firewall +``` + +The client also accepts `-f` if required. diff --git a/tools/hyperssh.md b/tools/hyperssh.md new file mode 100644 index 0000000..48041cd --- /dev/null +++ b/tools/hyperssh.md @@ -0,0 +1,66 @@ +# Hyperssh + +A utility to facilitate SSH operations via the [HyperDHT](../building-blocks/hyperdht.md). + +> [GitHub (Hyperssh)](https://github.com/mafintosh/hyperssh) + +* [Installation](hyperssh.md#installation) +* [Basic usage](hyperssh.md#basic-usage) +* [Windows RDP](hyperssh.md#windows-rdp) + +### Installation + +Install with [npm](https://www.npmjs.com/): + +```bash +npm install -g hyperssh // ssh / fuse client stubs +npm install -g hypertele // hyperswarm server proxy +npm install -g hyper-cmd-utils // keygen utils +``` + +### Basic usage + +On a server or a machine running an ssh-server, run: + +```bash +hyper-cmd-util-keygen --gen_seed +-> SEED + +hypertele-server --seed SEED -l 22 +-> PEER_KEY +``` + +This will start announcing the server on the DHT and will display the Noise Public Key of the server. + +To connect to the server from another machine, pass the keypair to the `hyperssh` command, along with an optional username: + +```bash +hyperssh -s ab01f... -u maf +hyperssh -s ab01f... -u maf -i keypair.json +``` + +There is no need to remember hostnames any more. + + +> Under the hood, Hyperswarm performs UDP holepunching. So the server should be accessible even if it is located on a home network. Refer to identity management for more information. + + +### Windows RDP + +Hyperssh can also be used with Windows RDP to remotely log in to Windows machines over Hyperswarm. + +**Ensure RDP is enabled on the computer that is going to be logged into (the server), and on that computer run:** + +```bash +hypertele-server --seed SEED -l 3389 +``` + +**Then on another computer (client), anywhere on the internet, ssh into the server:** + +```bash +hyperssh --rdp -s ... +``` + +## The hyper-cmd system + +The Hyperssh also supports the hyper-cmd system. Refer to [Identity management](https://github.com/prdn/hyper-cmd-docs/blob/main/identity.md) and [Host resolution](https://github.com/prdn/hyper-cmd-docs/blob/main/resolve.md) for additional information. diff --git a/tools/hypertele.md b/tools/hypertele.md new file mode 100644 index 0000000..53193b5 --- /dev/null +++ b/tools/hypertele.md @@ -0,0 +1,126 @@ +# Hypertele + +A swiss-knife proxy powered by [HyperDHT](../building-blocks/hyperdht.md)! + +> [GitHub (Hypertele)](https://github.com/bitfinexcom/hypertele) + +* [Installation](hypertele.md#installation) +* [Basic usage](hypertele.md#basic-usage) + +### Installation + +Install with [npm](https://www.npmjs.com/) + +```bash +npm install -g hypertele // hyperswarm server proxy +npm install -g hyper-cmd-utils // keygen utils +``` + +### Basic usage + +#### Server + +#### **Standard pipe server** + +```bash +hypertele-server --help +``` + +**Create a JSON config file for the server** + +```javascript +{ + "seed": "SEED", + "allowed": [ + "CLIENT_PEER_KEY", + ... + ] +} +``` + +| Options | Description | +| ----------------- | ------------------------------------------------------- | +| **`-l `** | port of the local service exposed to the peers | +| **`--cert-skip`** | skip certificate check when connecting to local service | +| **`--seed SEED`** | seed (command-line) | + +#### Examples + +```bash +hypertele-server -l 22 -c config-server.json +hypertele-server -l 22 --seed XXX +`````` + +> The above-mentioned command will print out the pubkey. + +### Pub + +**Pub server** + +```bash +hypertele-pub --help +``` + +**Create a JSON config file for the server** + +```bash +{ + "seed": "SEED", + "allowed": [ + "CLIENT_PEER_KEY", + ... + ] +} +``` + +```yaml +options: + +-l PORT : port of the local service to expose to the peers +--seed SEED : seed (command-line) +``` + +#### Examples + +```bash +hypertele-pub -l 5555 -c config-server.json +hypertele-pub -l 5555 --seed XXX +``` + +> The above-mentioned command will print out the pubkey. + + +### Client + +```bash +hypertele --help +``` + +**Create a JSON config file for client** + +```javascript +{ + "peer": "SERVER_PEER_KEY" +} +``` + +| Options | Description | +| -------------------------- | ------------------------------ | +| **`-s `** | server peer key (command-line) | +| **`-i `** | keypair file | + +#### Examples + +```bash +hypertele -p 1337 -c config-client.json +hypertele -p 1337 -s PUBKEY_FROM_SERVER -i keypair.json +telnet localhost 1337 +``` + +### The hyper-cmd system + +Hypertele also provides support for the hyper-cmd system! + +Learn more about identity management and host resolution using hyper-cmd: + +> [Github (Hyper-cmd-docs)](https://github.com/prdn/hyper-cmd-docs)