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.
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.
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.
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.
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.
All of the tasks that you normally accomplish with the Control Panel can be done with Tugboat.
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.
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>
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.
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.
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.
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
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.
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.
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>
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
And if you are using Oh My Zsh there is a custom plugin for tugboat at https://github.com/DimitriSteyaert/Zsh-tugboat
Tugboat is quite cool, but it looks like it doesn’t support mosh out of the box. So I wrote a little script that sort of hacks this functionality:
Is the ability to pass userdata available, or will it be available in tugboat?
strange, but my last comment was trimmed, and I can not edit that… here is the full version: Somebody should mention that
system_timer
gem is only needed, if you are running ruby less than 1.9.0Nevermind, it’s been fixed.
Tugboat is not working now, please fix
@Shelby: You can run <pre>tugboat images -g</pre> to get a listing of all images and their IDs.
Very cool. Is there a listing of the available default images? This looks to default to Ubuntu 12.04 x64, what would the default image ID be for Ubuntu 13.04 x64?