:: HOME :: TUTORIALS :: TIPS :: DOWNLOADS :: LINKS :: CONTACT :: ABOUT ::

Jake's GNU Screen Tutorial

Copyright ©2005 Jake Howe.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license can be found here.

Document Revision History:
Original Version: July 9, 2005

The GNU screen utility is best described as a terminal multiplexing utility. In a nutshell, screen allows you to have multiple virtual terminal instances over a single terminal connection. Throughout this document I'll refer to these virtual terminal instances as windows. You can create, close, name & navigate through virtual windows with simple CTRL+a command sequences. Don't be alarmed if you're a habitual user of this key sequence to move to the beginning of the command line. You can change screen's behavior through /etc/screenrc or ~/.screenrc. Although, would it really be so hard just to press the HOME key instead? :) While on the topic of the screenrc you should probably check the /etc/screenrc file that came with your distribution for customized command sequences (key bindings). Ferdora has modified several key bindings that it has deemed "stupid & dangerous".

Perhaps the most renowned feature of screen is its ability to detach and reattach a session without losing state on any of the virtual terminals. Another handy feature is the ability to split a single terminal window into multiple simultaneously viewed terminals called regions. screen even has the ability to share a session with multiple users in a collaborative way. I'll cover all of these in this tutorial.

Please refrain from sending me those "yeah, but..." emails regarding similar stateless session solutions like VNC. VNC is cool (I use it), but perhaps a little overkill (read as bloaty) for some situations. For example, you may only have ssh connectivity (over a low bandwidth connection) to your destination host. And hey, some of us still prefer the command line for most administration tasks.

This tutorial was written using Screen version 4.00.02 (FAU) 5-Dec-03 on Fedora Core 3.

For additional information outside the scope of this tutorial, refer to screen's man page (man screen) or info document (info screen).

Basic Usage

Here's a list of the most common commands to help you get started creating & navigating your screen sessions.

You'll see several references to the "status bar" throughout this tutorial. Depending on your distribution or whether you're in a GUI or console mode, this can either be the titlebar of your xterm or at the bottom of the terminal screen.

To start a screen session...
```
 $ screen 
```
or to start a session with a name (more on this later)...
```
 $ screen -S LogTails
```
To create a new window and change into it...
```
CTRL+a c
```
To navigate through the windows...
Switch to the next window
```
CTRL+a n
```
Switch to the previous window
```
CTRL+a p
```
Switch directly to window number 3
```
CTRL+a 3
```
To set a name for a window...
```
CTRL+a A
```
You will be prompted for a name with "Set window's title to:".

This can make finding & selecting a window much easier. By default all windows are named "bash" or whatever your shell is.
View a list of windows...
This will display a selectable list of windows. Use the arrow keys to choose one.
```
CTRL+a "
```
This will temporarily display a list of available windows on your status bar. This isn't very useful for lists that are too long to fit in the status bar.
```
CTRL+a w
```
To lock a session...
```
CTRL+a CTRL+x
```
This will lock the screen session requiring the user to enter their password to unlock.
To close windows...
Use normal means at the command prompt
```
   CTRL+d
   exit 
```
Forcibly kill a window. You will be asked for confirmation.
```
CTRL+a k
```
Fedora has changed this to K (capitalized). Check your /etc/screenrc for custom bindings.

The entire screen session will close-out when the last window has been closed. You should see this...
```
[screen is terminating]
```

Detach & Reattach

Ok, so you should be able to create a screen session and navigate the windows. Let's look at how to detach & reattach sessions with active windows

To detach a screen session...
```
CTRL+a d
```
You should find yourself at a command prompt with this message...
```
[detached]
```
To list available screen sessions...
After you've detached a screen session you won't see any processes named "screen" in the process list. The individual programs you left running will all appear as separate processes. So how do we know what screen sessions are floating around, you ask?

Here's one way...
```
ls -1 /tmp/screens/S-`whoami`
```
Here's a better way...
```
   $ screen -list
   There are screens on:
           9571.pts-1.testbox     (Detached)
           9651.LogTails          (Detached)
   2 Sockets in /tmp/screens/S-testuser.
   
```
This shows me that I have 2 screen sessions running and both are currently detached. The output may look a little cryptic, but it's really not so bad. For the first session; 9571 is the PID, pts-1 is the TTY & testbox is the hostname. The second session is a "named" session (screen invoked with the -S switch).
To reattach a screen session...
Here's how to reattach a session in its simplest form...
```
$ screen -r
```
This works if you only have one single session out there and it is currently detached.

How about a scenario where you want to attach a session that you left attached at another terminal...
```
$ screen -x
```
This will attach that session to your terminal, but the original terminal still has it attached as well. Try this with 2 xterms. Whatever you type in one terminal will show up in both.

In our same scenario, if you wanted to detach the session from the remote terminal & reattach to your terminal...
```
$ screen -dr
```
Remember our screen -list above that had multiple sessions? We could attach one of those sessions by using several different methods.

By PID...
```
$ screen -r 9571
```
By the socket filename...
```
$ screen -r 9571.pts-1.testbox
```
By name...
```
$ screen -r LogTails
```

Copy & Paste

Here's a feature that can be useful if you're stuck in console mode & don't have a mouse available. screen has its own built in buffer for copying & pasting text into the same or other windows.

Enter copy mode by pressing CTRL+a [

The status bar will read "Copy mode" with column & line information.
Move the cursor to the beginning of the block you wish to copy using standard vi keys or the arrow keys.
Press the ENTER key.

The status bar will read "First mark set" with column & line information.
Move the cursor to the end of the block you wish to copy using standard vi keys or the arrow keys.
Press the ENTER key.

The status bar will read "Copied X characters into buffer".
Paste the copied text with CTRL+a ]

Regions

Regions are one of my favorite parts of screen. It works much like the old splitvt command. This feature allows you to split a window in half giving you 2 terminals in view at the same time. You can further split a region into more regions, but real estate is quickly used up by the multiple dividing lines between the regions.

To create a new region (split)...
```
CTRL+a S
```
You'll notice that there's no prompt in the new region. We need to move to that region & create a new window.
To switch to the next region...
```
CTRL+a TAB
```
Use the CTRL+a c command to create the new window in the empty region.
To remove the currently focused region...
```
CTRL+a X
```
This won't destroy the window in that region. It will only remove the split in the screen.

Multiuser mode

This is one of the more advanced features of screen. It also happens to pose a bit of a security risk.

We'll use a very simple scenario for this one. Let's say Jake wants to share access to a screen session with Bob. Jake & Bob both have accounts on the system.

In order to enable multiuser mode the screen binary must be setuid for root.
```
# chmod u+s /usr/bin/screen
```
Jake starts a screen session.
```
jake$ screen -S shared
```
Jake must enable multiuser mode.
```
CTRL+a : multiuser on
```
This could be added to ~/.screenrc to have it enabled for all sessions, but case-by-case is probably safer.
Jake must add Bob to the access control list for his session.
```
CTRL+a : acladd bob
```

Bob lists the screen sessions that Jake has available.

   bob$ screen -list jake/
   There are several screens on:
           1951.pts-1.testbox     (Private)
           1994.shared            (Multi, attached)
   2 Sockets in /tmp/screens/S-jake.

This shows us that Jake has 2 sessions. The second session named "shared" is a multiuser session & Jake already has it attached.

Bob attaches Jake's multiuser session.
```
bob$ screen -x jake/shared
```
Bob could also connect using the PID.

Jake can check to see if Bob is connected to his session.

CTRL+a *

This brings up a list of users in a screen session.

   term-type   size         user interface           window
   ---------- ------- ---------- ----------------- ----------
   xterm       80x24        bob@/dev/pts/11          0(email)     rwx
   linux       80x24        jake@/dev/tty1           0(email)     rwx

                 [Press Space to refresh; Return to end.]

Jake can boot Bob from his screen session.
```
CTRL+a : acldel bob
```
Bob is immediately disconnected and sees...
```
   [remote detached]
   bob$
   
```