Rescuing Running Jobs

It happens to everyone: you start a long job straight in your SSH session, and only then realise you should have started it inside screen. This chapter covers the two different things "adding a job to a screen" can mean — rescuing a job that's already running outside screen, and starting a new job inside a session that's already running — and is honest about what each method can and can't do.

The Honest Answer First

Screen itself has no command to adopt a running process. A process's controlling terminal is set when it starts, and ordinary tools can't change it afterwards. That leaves three real options:

Method 1: Protect It With disown

If you only need the job to keep running, Chapter 7's sequence is enough, and it needs no extra software:

The job survives, but it's still writing to your old terminal, and you can never get it back to type into. For anything you want to watch or control later, you need reptyr.

Method 2: reptyr

reptyr, written by Nelson Elhage, attaches a running program to a new terminal. It uses the kernel's debugging interface, ptrace, to make the process switch its controlling terminal to the one you run reptyr in. Run it inside a screen window, and the job becomes part of that window: its output appears there, and Ctrl-C and Ctrl-Z reach it normally.

The window now shows the job's output. You can detach with Ctrl-a d, log out, and reattach later exactly as if you'd started the job inside screen in the first place.

The ptrace permission problem

Because ptrace is also what debuggers use to inspect other programs, many distributions restrict it for security, through the Yama setting /proc/sys/kernel/yama/ptrace_scope:

reptyr's limits

• It works most reliably on a single process. A pipeline, or a program that has started its own child processes on the same terminal, may not move cleanly; newer versions have a -T ("steal") mode designed for those cases.
• It can only take your own processes (or anyone's, with sudo).
• Output the job wrote to the old terminal before the move isn't copied over — you only see what it writes afterwards.
• Programs that draw full-screen interfaces may need a redraw (often Ctrl-L) after the move.

Method 3: Restart It Properly

If the job can be safely stopped and started again — it hasn't done much yet, or it can resume from where it left off, as rsync can — the simplest and most reliable fix is to stop it and start it again inside screen. Don't reach for reptyr just to avoid a restart that costs nothing.

Adding a New Job to a Session That's Already Running

The other meaning of "add a job to a screen" is starting a new command inside an existing session, often without attaching. Screen's -X option sends a command to a session, and screen is itself one of screen's commands: it opens a new window.

From inside the session you can do the same thing with screen -t title command (Chapter 4). Chapter 9 covers -dm and -X in depth, including typing commands into an existing window.

Hands-On Exercises