How To Use Tugboat to Manage DigitalOcean Droplets from a Terminal

Introduction

---

If you are reading this article, then you are probably familiar with how to manage your DigitalOcean droplets from within the Control Panel.

Tugboat is an exciting open source application written by Jack Pearkes and other contributors that can be used to manage your droplets from a command line interface.

In this guide, we will install and configure Tugboat using an Ubuntu 14.04 VPS. This will act as the “control” droplet for our other DigitalOcean droplets.

Table Of Contents

---

• How To Install Tugboat
• How To Generate an API Key
• Initial Tugboat Configuration
• Connect to a Droplet
• Droplet Management
  • Retrieve Droplet Information
  • Droplet Power Management
  • Droplet Creation and Destruction
  • Droplet Creation Settings
  • Miscellaneous Administration
  • How To Use the Help System
• Other Considerations
  • How To Set Up SSH Keys
  • How To Use Screen with Tugboat
• Conclusion

<a id=“install”></a>How To Install Tugboat

---

Log into your new droplet through SSH or by clicking the Console Access button on the droplet page.

Tugboat is a Ruby application, which means that we can install it easily using the RubyGems package manager.

First, we need to install Ruby from Ubuntu’s default repositories:

sudo apt-get update
sudo apt-get install ruby ruby-dev build-essential

Now, we can install tugboat using RubyGems. We will also install system_timer to avoid a repeated notification message later:

sudo gem install tugboat
sudo gem install system_timer

We now have Tugboat installed on our system. Let’s set it up.

<a id=“api_key”></a>How To Generate an API Key

---

In order for Tugboat to manage your droplets, you will have to authorize it to access your account through the DigitalOcean API interface. This is a simple procedure.

Log into your account on the DigitalOcean website.

Click on API on the left-hand navigation bar in the Control Panel.

You should see a Client ID pre-populated with a value that references your account.

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/tugboat/client_id.png” alt =“DigitalOcean Client ID” />

Below this, if you have not set up an API Key yet, you will be told to generate a key:

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/tugboat/generate_key.png” alt =“DigitalOcean Generate Key” />

Your API key will be generated. Copy this key to a secure location. It will not be available to you again once you click out of this page. You will need to regenerate the key if you lose it.

You need both the Client ID and the API key to configure Tugboat, so keep this window open.

<a id=“config”></a>Initial Tugboat Configuration

---

Tugboat includes an initial configuration command that can be called by typing:

tugboat authorize

You will be asked a series of questions that are necessary to associate tugboat with your DigitalOcean account.

For the first two questions, copy and paste the values from the API page that you have opened:

<pre> Enter your client key: <span class=“highlight”>Client_ID_from_API_page</span> Enter your API key: <span class=“highlight”>API_Key_from_API_page</span> </pre>

The next three questions involve the SSH authorization details necessary to connect to all of your droplets.

Press Enter to accept the default SSH key path. Depending on how you usually connect to your other droplets, you may wish to change the SSH user to another value (such as root). Press Enter to accept the default SSH port unless you connect to your droplets using a different port.

<pre> Enter your SSH key path (optional, defaults to ~/.ssh/id_rsa): Enter your SSH user (optional, defaults to demo): <span class=“highlight”>root</span> Enter your SSH port number (optional, defaults to 22): </pre>

Next, you will be taken through the default settings that will be used for new droplet creation. For now, we will press Enter through these prompts to accept the default values.

Enter your default region ID (optional, defaults to 1 (New York)): 
Enter your default image ID (optional, defaults to 284203 (Ubuntu 12.04 x64)): 
Enter your default size ID (optional, defaults to 66 (512MB)): 
Enter your default ssh key ID (optional, defaults to none): 

You should receive a reply confirming that your keys were accepted:

Authentication with DigitalOcean was successful.

The selections that we have just made are stored in a hidden file in your home directory called .tugboat:

nano ~/.tugboat

---

---
authentication:
  client_key: xxxxxxxxxxxxxxxxxxxxxx
  api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
defaults:
  ssh_key: ""
  size: "66"
  image: "284203"
  region: "1"
ssh:
  ssh_port: "22"
  ssh_user: root
  ssh_key_path: /home/demo/.ssh/id_rsa

If you ever need to re-generate your API Key, you will need to change it here after you re-generate it on the DigitalOcean website.

Afterwards, you will want to re-verify that the application can associate correctly by typing:

tugboat verify

The SSH section should be self-explanatory if you choose to modify it.

We will cover how to find the information needed to change the defaults section later.

<a id=“connect”></a>Connect to a Droplet

---

We now have enough configured to explore Tugboat.

Every tugboat command begins with tugboat followed by an action.

Let’s list the droplets that we have in our account:

tugboat droplets

---

irssi (ip: xxx.xxx.xxx.xx, status: active, region: 1, id: 3150xx)
tug (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3372xx)
test (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 3373xx)
DigitalOcean20Dollar (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3520xx)
archtestmail (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 4328xx)
TugWrite (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 4496xx)

This is analogous to your droplet’s screen in the web interface. It lists each droplet that we can interact with.

Let’s SSH into one of our droplets by using tugboat:

tugboat ssh ourDroplet

---

Droplet fuzzy name provided. Finding droplet ID...done, 3150xx (ourDroplet)
Executing SSH (ourDroplet)...
Warning: Identity file /home/demo/.ssh/id_rsa not accessible: No such file or directory.
root@xxx.xxx.xxx.xx's password:

As you can see, we are asked for the password to root@ourDroplet. If we had set up SSH keys, we would have been connected without needing any additional interaction.

Exit out of the droplet to get back into the Tugboat droplet.

A feature that is present throughout the Tugboat experience is “Fuzzy name matching”. This means that Tugboat will recognize any command that is unambiguous enough.

For instance, we could have reached the same result by typing:

tugboat drop

Tugboat will expand drop to mean droplets and execute it without any additional input.

This works with droplet names as well.

<a id=“management”></a>Droplet Management

---

All of the tasks that you normally accomplish with the Control Panel can be done with Tugboat.

<a id=“get_info”></a>Retrieve Droplet Information

---

To get more information about a specific droplet, type:

<pre> tugboat info <span class=“highlight”>droplet_name</span> </pre>

Name:             irssi
ID:               3150xx
Status:           active
IP:               xxx.xxx.xxx.xx
Region ID:        1
Image ID:         479972
Size ID:          66
Backups Active:   false

This is mostly the same information that we are given in-line with the droplets command, but there are some additional fields, such as the Image ID, Size ID, and whether backups are enabled.

<a id=“power_management”></a>Droplet Power Management

---

We can control the power-on state of our droplets by issuing the appropriate commands.

To boot a droplet that is currently down, type:

<pre> tugboat start <span class=“highlight”>droplet_name</span> </pre>

To reboot a droplet, type:

<pre> tugboat restart <span class=“highlight”>droplet_name</span> </pre>

To power down a droplet, type:

<pre> tugboat halt <span class=“highlight”>droplet_name</span> </pre>

<a id=“create_destroy”></a>Droplet Creation and Destruction

---

Droplets can be deleted by simply typing:

<pre> tugboat destroy <span class=“highlight”>droplet_name</span> </pre>

Because this has irreversible consequences, you are asked to confirm the action before the droplet is destroyed:

Droplet fuzzy name provided. Finding droplet ID...done, 4530xx (blahblah)
Warning! Potentially destructive action. Please confirm [y/n]:

Type y and Enter to destroy the droplet.

To create a droplet, you can use the following syntax:

<pre> tugboat create <span class=“highlight”>droplet_name</span> </pre>

Without additional arguments, your droplet will be created according to the criteria in the default section of your ~/.tugboat file.

We can modify this behavior by passing some optional flags. Use the “help” command with the “create” action as an additional argument to get the usage details of create:

tugboat help create

---

Usage:
  tugboat create NAME

Options:
  -k, [--keys=KEYS]  # A comma separated list of SSH key ids to add to the droplet
  -s, [--size=N]     # The size_id of the droplet
  -r, [--region=N]   # The region_id of the droplet
  -i, [--image=N]    # The image_id of the droplet

Create a droplet.

As you can see, we can embed any of the SSH keys that we have uploaded to the site, and specify the size, region, and base image for the creation process.

We will discuss how to find the appropriate values for these parameters below.

<a id=“creation_settings”></a>Droplet Creation Settings

---

We can choose the settings that we want to use for droplet creation by querying the site for the available options.

To see the list of sizes and their associated IDs, type:

tugboat sizes

---

Sizes:
512MB (id: 66)
1GB (id: 63)
2GB (id: 62)
4GB (id: 64)
8GB (id: 65)
16GB (id: 61)
32GB (id: 60)
48GB (id: 70)
64GB (id: 69)
96GB (id: 68)

As you can see, each size is associated with an id, which we use to reference that value.

So if we wanted to create a 2GB droplet, we could issue the following command:

<pre> tugboat create -s 62 <span class=“highlight”>droplet_name</span> </pre>

A similar command is available to see the available regions:

tugboat regions

---

Regions:
New York 1 (id: 1)
Amsterdam 1 (id: 2)
San Francisco 1 (id: 3)
New York 2 (id: 4)

Embedding an uploaded SSH key within a new droplet is easy. You can find them by issuing:

tugboat keys

---

SSH Keys:
Work key (id: 12345)
Home key (id: 56789)

The command to view the available images is slightly more complex, only because by default, it shows the snapshots that you have saved:

tugboat images

---

My Images:
Ubuntu Basic setup (id: 4799xx, distro: Ubuntu)
Arch default (id: 4811xx, distro: Arch Linux)
LAMP Ubuntu (id: 4908xx, distro: Ubuntu)
LAMP Success (id: 5838xx, distro: CentOS)

You can select any of these to use as a base image by using the associated ID.

To get a more complete list, including all of the pre-configured distro and application images, add the global flag:

tugboat images -g

---

My Images:
. . .

Global Images:
CentOS 5.8 x64 (id: 1601, distro: CentOS)
CentOS 5.8 x32 (id: 1602, distro: CentOS)
Debian 6.0 x64 (id: 12573, distro: Debian)
Debian 6.0 x32 (id: 12575, distro: Debian)
. . .

You will see a large list of available images. These are referenced by their ID as well, just like the other settings.

These are the pieces of information that we would need to alter the values of the “default” settings in the ~/.tugboat configuration file.

<a id=“misc_admin”></a>Miscellaneous Administration

---

To take a snapshot using the snapshot command, type:

<pre> tugboat snapshot <span class=“highlight”>name_of_snapshot</span> <span class=“highlight”>droplet_to_snapshot</span> </pre>

To resize a droplet, you need to supply the new size criteria to the resize command. Your droplet must be powered on to run this successfully:

<pre> tugboat resize <span class=“highlight”>droplet_name</span> -s <span class=“highlight”>size_ID</span> </pre>

To reset the root password on a droplet, simply issue the password-reset command:

<pre> tugboat password-reset <span class=“highlight”>droplet_name</span> </pre>

You will receive an email with the new password that has been set for the droplet.

<a id=“help”></a>How To Use the Help System

---

Tugboat includes a great help system. You can access the general help at any time by typing:

tugboat help

This will give you a list of every command that you can use.

To get more fine-grained help, specify a command name after help.

For instance, to get help with the authorize command, type:

tugboat help authorize

<a id=“other”></a>Other Considerations

---

<a id=“ssh_keys”></a>How To Set Up SSH Keys

---

Like most applications that utilize SSH, Tugboat benefits from properly configured SSH keys.

If you have already created a public and private key pair and uploaded the public key to your DigitalOcean page to use for droplet creation, you can copy the private key to your Tugboat droplet.

To do this, log into the computer that you use to access your DigitalOcean droplets. Change to your ssh configuration directory:

cd ~/.ssh

Use scp to copy the private key to the Tugboat droplet:

<pre> scp id_rsa <span class=“highlight”>tugboat_username</span>@<span class=“highlight”>tugboat_droplet_ip</span>:/home/<span class=“highlight”>tugboat_username</span>/.ssh/ </pre>

Log into your Tugboat droplet. Change the ownership of the id_rsa file to match the username you are using with Tugboat.

<pre> sudo chown <span class=“highlight”>tugboat_username</span>:<span class=“highlight”>tugboat_username</span> ~/.ssh/id_rsa </pre>

You should now be able to connect to droplets that have been created with that key without a password:

<pre> tugboat ssh <span class=“highlight”>example_droplet</span> </pre>

Remember to alter your configuration file to use this key for new droplet creation!

If you have not already done so, follow this article to set up key pairs and uploaded a public key to your DigitalOcean page.

<a id=“using_screen”></a>How To Use Screen with Tugboat

---

One tool that is incredibly useful with Tugboat is screen, a terminal multiplexer.

Put simply, this tool allows you to manage multiple terminal sessions from a single window. You can create and switch between several “windows”, each of which is an independent shell session.

This is especially handy when dealing with multiple SSH sessions, which is exactly what Tugboat allows you to do.

Install screen on Ubuntu by typing:

sudo apt-get update
sudo apt-get install screen

Start the application by typing:

screen

You now are using a terminal session that is actually operating within screen.

You can connect to a droplet here by typing:

<pre> tugboat ssh <span class=“highlight”>droplet1</span> </pre>

Now, create a new window by typing:

Ctrl-a c

That is, hold the control key, and hit the a key, followed by the c key. This creates a new window.

Connect to a new droplet in this window by typing:

<pre> tugboat ssh <span class=“highlight”>droplet2</span> </pre>

You can switch between the windows by typing:

Ctrl-a n

You can destroy windows by typing:

Ctrl-a k

To learn more about how to use screen, click here. To learn how to use tmux, a similar terminal multiplexer, click here.

<a id=“conclusion”></a>Conclusion

---

Tugboat is a great tool for managing your droplets without ever having to leave a terminal environment. It provides a unified interface to keep track of your droplets and manage your sessions.

Configuring Tugboat correctly eliminates the hassle of having to either perform continuous maintenance on a hosts file or flip back and forth between terminal and browser windows.

If you find any issues with the software or wish to contribute to the project, please visit the Tugboat page on Github.

Thank you Jack Pearkes and the Tugboat team for providing the DigitalOcean community with such a valuable tool!

<div class=“author”>By Justin Ellingwood</div>

ip=$(tugboat info $1 | grep -Eo '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}')
mosh root@$ip```

Save it something like tugboat-mosh.sh, chmod +x it, and then add it optionally to your bash profile so that you can call it up via 'tugboat-mosh' for example. If anyone has a better idea, please don't hesitate to suggest - I've been playing with tugboat with all of 15 minutes and I'm hardly a bash expert either.