tutes-dump/site-tutorials/screen.html

<h1>Screen</h1>

<style type="text/css">
	.kbd { font-weight: bold; }
	code, .prompt { background-color: black; color: white; padding: 5px; }
	.prompt { padding: 0 ; 
	h1 { font-size: 180%; }
	h2 { font-size: 160%; }
	h2 { font-size: 140%; }
	#rcs_tag { font-size: 70% ; }
</style>

<div id="toc">

<span>Contents</span>

<ol>
	<li><a href="#intro">Introduction</a></li>
	<li><a href="#start">Starting Screen, detaching and reattaching</a></li>
	<li><a href="#multiwin">Multiple windows</a></li>
	<li><a href="#multisession">Multiple sessions</a></li>
	<li><a href="#split">Splitting windows</a></li>
	<li><a href="#share">Sharing screen sessions</a></li>
	<li><a href="#screenrc">.screenrc</a></li>
	<li><a href="#cheatsheet">Cheat sheet</a></li>
	<li><a href="#resources">Resources</a></li>
</ol>

</div>

<h2><a name="intro"></a>Introduction</h2>

<p>
<a href="http://savannah.gnu.org/projects/screen/">Screen</a> is a
<q>terminal multiplexer</q>, i.e., it will let you have multiple virtual
terminals in a single window. You will also be able to 1) <q>detach</q> a
screen session, and then detach it in a later moment; 2) share screen
sessions.
</p>

<p>
In this tutorial <span class="prompt">$ </span>&nbsp;
indicates a terminal prompt (just for visual convenience).
</p>

<p>
A Screen command is usually of the form <span class="kbd">CTRL-a KEY</span>,
i.e., you'll have to press the <span class="kbd">CTRL</span> key along
with <q>a</q>, followed by a generic KEY. (Screen's default escape key is
<span class="kbd">CTRL-a</span>.)
</p>

<p>
You'll need to be a <a href="http://sdf.org/?join#meta">MetaARPA</a> member
in order to use Screen on SDF
</p>

<p>
If you want a <q>screencast</q> tutorial, type:
</p>

<code><span class="prompt">$ </span><span class="command">ttyplay /ftp/pub/users/jecxjo/howto/screen</command></code>

<p>
on a terminal connected to SDF.</p>

<p>
Alternatively, you can watch the screencast 
online at <a href="http://playterm.org/r/brief-screen-tutorial-1307563176">PlayTerm.</a>
</p>


<h2><a name="start"></a>Starting Screen, detaching and reattaching</h2>

<p>
You can run screen by typing:
</p>

<code><span class="prompt">$ </span><span class="command">screen</span></code>

<p>
When you run it, a window with some copyright and some other info will show
up, with <q>[Press Space or Return to end.]</q> at the bottom. OK, as it
says, you can now press <q>Space</q> or <q>Enter</q>. You will then see your
shell prompt and nothing else. That's fine: you can now run your programs as
usual, the difference is that they will run under a Screen session.
You can <q>detach</q> it by typing <span class="kbd">CTRL-a d</span>. Screen will keep
your session running. Now if you logout, then log back in, and type:
</p>

<code><span class="prompt">$ </span><span class="command">screen -r</command></code>

<p>
you'll see your terminal as you left it when you detached Screen!
</p>

<p>
If you lost connection, or simply forgot to detach Screen, and want to resume your session
by typing:
</p>

<code><span class="prompt">$ </span><span class="command">screen -d -r</command></code>

<p>
The <q>-d</q> flag will detach Screen, while <q>-r</q> will reattach. There
are various types of <q>detach</q> and </reattach</q> flags. For instance,
if you type the previous command and there was no screen session to be
resumed, you'll get a <q>There is no screen to be detached.</q> message. In
this case you'll probably need:
</p>

<code><span class="prompt">$ </span><span class="command">screen -d -R</command></code>

<p>
which will first create a new session (or rettach an existing one).
</p>

<h2><a name="multiwin"></a>Multiple windows</h2>

<p>
You can create various windows under your Screen session, each one running
their own program. When you are in a Screen session, typing:
</p>

<code><span class="prompt">$ </span><span class="command">screen</command></code>

<p>
will create a new window, leaving the previous window untouched, though not
visible. Instead of typing <q>screen</q>, you can use the shortcut <span
class="kbd">CTRL-a c</span>. 
</p>

<p>
You can create as many windows as you want. You can swith between windows
with <span class="kbd">CTRL-a n</span> (next window) and <span
class="kbd">CTRL-a p</span> (previous window). It's also possible to select
windows by number. Typing <span class="kbd">CTRL-a 1</span> will open window
number 1, <span class="kbd">CTRL-a 2</span>, to window 2, and so on.
</p>

<p>
How do you know what's a window number? Well, you can type <span
class="kbd">CTRL-a "</span> (yeah, that's a double quote). In that case a menu
with a windows list will open. You can select a number and press enter to go
to that screen. An easier way is to have a <q>hard status line</q> that
shows you each window number. For doing this in a permanent manner, you'll
have to create a <q>.screenrc</q> (Screen's customization file) in your
$HOME directory and write in it the following lines:
</p>

<pre>
hardstatus alwayslastline
hardstatus string "%{WK}%-LW %{Y.}%n%f* %t%{-}%+LW"
</pre>

<p>
(We will see what that crazyness means later.)
</p>

<p>
For your .screenrc file to be read by Screen, you'll have to start a new
session. BTW, a Screen session ends when the last window is closed.
</p>

<h2><a name="multisession"></a>Multiple sessions</h2>

<p>
It's possible to have various Screen sessions running, each one with their
own set of windows open. If you started Screen by just typing <q>screen</q>,
a new session is created. If you detach and type <q>screen</q> again, a new
session will start. If you now type:
</p>

<code><span class="prompt">$ </span><span class="command">screen -ls</command></code>

<p>
it will give you a list of Screen sessions like this:
</p>

<pre>
        3340.pts-6.HOST        (Detached)
        4522.pts-8.HOST        (Attached)
2 Sockets in /tmp/screens/S-YOU
</pre>

<p>
where HOST is the hostname and YOU is your username.
</p>

<p>
You can reattach a screen session by name. Say for instance that you want to
resume the <q>4522.pts-8.HOST</q> session. In this case you'll have to type:
</p>

<code><span class="prompt">$ </span><span class="command">screen -r 4522.pts-8.HOST</command></code>

<p>
Obviously <q>4522.pts-8.HOST</q> is not a very userfriendly session name.
You can give a meaningful name by starting screen as:
</p>

<code><span class="prompt">$ </span><span class="command">screen -S mysession</command></code>

<p>
where <q>mysession</q> is the name you want to give to your session (e.g.,
<q>work</q>).
</p>

<h2><a name="split"></a>Splitting windows</h2>

<p>
It could be useful to split a window so that you can have two programs
running on the viewport. In this case, type <span class="kbd">CTRL-a
S</span> and you'll see that the window will be split in two regions, with
the one at the bottom blank. You can swith to it with <span
class="kbd">CTRL-a TAB</span> (TAB is the tab key) and then select a window
by typing its number, or <q>p</q> (previous) or <q>n</q> (next), e.g., <span
class="kbd">CTRL-a 2</span>. You can always swith through regions with <span
class="kbd">CTRL-a TAB</span>.
</p>

<p>
It's possible to split the window in more then two regions, each time by
typing <span class="kbd">CTRL-a S</span>
</p>

<p>
If you want to split a window vertically, you'll have to either use a
patch[1] or use a recent version of Screen.
</p>

<h2><a name="share"></a>Sharing screen sessions</h2>

<p class="body">
<p> The scenario is...</p>
<p>HOSTUSER and SOMEUSER are both MetaARPA members logged into sverige.</p>
<p>HOSTUSER wants to give SOMEUSER read only access to screen session of HOSTUSER.</p>
<p>HOSTUSER starts a screen session as normal.</p>
<p>Only three commands are needed for basic read only access to the current active window.</p>

<p>HOSTUSER types the following commands beginning with <span class="kbd">CTRL-a :</span> each time ( <i>control and 'a' followed by a colon </i>)</p>
<p><span class="kbd">CTRL-a:multiuser on<RETURN></span></p>
<p><span class="kbd">CTRL-a:password none<RETURN></span></p>
<p><span class="kbd">CTRL-a:aclchg SOMEUSER -w "#"<RETURN></span></p>
<p>SOMEUSER should exit screen first, then in the shell, type:</p>
<p><code><span class="prompt">$ </span><span class="command">screen -r HOSTUSER/</span></code></p>

<p>SOMEUSER now has read only access to the active window in HOSTUSER's screen session at the time of attaching.</p>

<p>HOSTUSER can verify SOMEUSER is attached by typing:</p>
<p><span class="kbd">CTRL-a*</span></p>
<p>HOSTUSER can disconnect SOMEUSER by typing:</p>
<p><span class="kbd">CTRL-a:acldel HOSTUSER<RETURN></span></p>

<p>HOSTUSER can verify SOMEUSER is no longer attached by typing:</p>
<p><span class="kbd">CTRL-a*</span></p>

<p>HOSTUSER can allow SOMEUSER access to additional commands.</p>
<p>The following commands allow SOMEUSER to cycle backwards and forward through the windows and detach.</p>
<p>HOSTUSER types:</p>
<p><span class="kbd">CTRL-a:aclchg SOMEUSER +x next</span></p>
<p><span class="kbd">CTRL-a:aclchg SOMEUSER +x prev</span></p>
<p><span class="kbd">CTRL-a:aclchg SOMEUSER +x detach</span><p>

<i><h4><p>Some notes:</p></h3></i>
<p class="note">** Screen version that was used "Screen version 4.00.03 (FAU) 23-Oct-06"</p>
<p class="note">** At the time of writing ( Tue Apr 17 23:01:50 IST 2012 ) all attempts at achieving the above read only functionality by editing .screenrc failed, usually resulting in SOMEUSER having FULL access to HOSTUSER's screen and shell account.</p>
<p class="note">** HOSTUSER might notice that screen resizes to fit the smaller of the two terminals.</p>
<p class="note">** After SOMEUSER is detachs HOSTUSER might try <span class="kbd">CTRL-aF</span> to resize the screen windows to fit the terminal.</p>
<p class="note">** For convenience and to reduce typing in screen HOSTUSER might want to have "multiuser on"  and "password none" in .screenrc. HOSTUSER's screen is still private until a user is permitted to attach with aclchg.</p>
<p class="note">** HOSTUSER will hear/see lots of bells if SOMEUSER tries to type into the screen session.</p>
<p class="note">** HOSTUSER can check what window is being view by SOMEUSER by looking at the output of <span class="kbd">CTRL-a*</span></p>
<p  class="note">** HOSTUSER might notice SOMEUSER appears to have rwx access in the output of <span class="kbd">CTRL-a*</span>  ...this is a bug or an undocumented feature.</p>
<p class="note">** SOMEUSER can remain attached even if HOSTUSER detachs.</p>
</p>

<h2><a name="screenrc"></a>.screenrc</h2>

<p>
As we previously saw, it is possible to customize Screen by writing settings
in a file named <q>.screenrc</q> in your $HOME directory. We will now some
useful Screen settings.
</p>

<h3>Avoiding the startup message</h3>

<p>
A full screen message with copyright and other stuff is usually displayed at
startup. This can get annoying. In order to avoid it, you can put in
your .screenrc the following:
</p>

<pre>
startup_message off
</pre>


<h3>Keybindings</h3>

<p>
It's possible to bind keys so that when you type <span
class="kbd">CTRL-a KEY</span> Screen willl open a new window launching some
program. For instance, if you write in your .screenrc file
</p>

<pre>
bind m screen -t mail 1 mutt
</pre>

<p>
each time you'll type <span class="kbd">CTRL-a m</span> a new window (named
<q>mail</q>)with mutt will be created. Be careful: when you bind a key,
you'll overwrite Screen's defaults (e.g., we just lost the <q>lastmsg</q>
key).
</p>


<h2><a name="cheatsheet"></a>Cheat sheet</h2>

<p>
TODO
</p>

<h2>Resources</h2>

<ul>
	<li><a href="http://aperiodic.net/screen/start"
		rel="external">http://aperiodic.net/screen/start</a>
	</li>
	<li><a href="http://www.bangmoney.org/presentations/screen.html"
		rel="external">http://www.bangmoney.org/presentations/screen.html</a>
	</li>
	<li>SDF has some <a href="http://sdf.org/?tutorials/dotfiles">annotated
		dotfiles</a>.
	</li>
</ul>

<h2>Notes</h2>

[1] <a href="http://fungi.yuggoth.org/vsp4s/"
	rel="external">http://fungi.yuggoth.org/vsp4s/</a>


<!--
<code><span class="prompt">$ </span><span class="command"></command></code>
-->

<hr />

<div id="rcs_tag">$Id: screen.html,v 1.8 2012/05/08 14:45:50 dickey Exp $</div>