Install Byobu at Login Without Losing Your Shell Exit

You will configure byobu-launcher-install so Byobu starts when you log in through SSH or on a local console, then confirm what changed and remove the automatic launch if you do not want it. Allow about ten minutes, plus one test login if you can open a second session.

This guide describes the installed Ubuntu package on this machine: Byobu 6.11-0ubuntu1.1. The utility is a shell script, and its manpage is dated 3 January 2010, so the exact files and messages below are tied to this installed implementation. Run it as the account that should get the automatic launcher. It normally needs no sudo.

1. Check the command and your login shell

Start by confirming that the command resolves to the package you expect and that you are looking at the correct home directory. This matters on a shared host or when you are connected as a different account.

$ command -v byobu-launcher-install
/usr/bin/byobu-launcher-install
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1
$ printf 'user=%s home=%s shell=%s\n' "$USER" "$HOME" "$SHELL"
user=YOUR_USER home=/home/YOUR_USER shell=/bin/bash

The final line is host-specific. If command -v prints nothing, stop here and install or repair Byobu through your normal package-management process. Do not run a copy of the script from an untrusted directory merely because it has the same name.

2. Save the files before changing login behaviour

The installer changes login configuration in your home directory. Before running it, make a dated backup of the files that already exist. The backup command below only copies existing files; it does not create empty replacements for files that are absent.

$ backup_dir="$HOME/byobu-launcher-backup-$(date +%Y%m%d-%H%M%S)"
$ mkdir -p -- "$backup_dir"
$ for file in .profile .bash_profile .bash_login .zprofile .hushlogin .config/fish/config.fish; do
>     if [ -e "$HOME/$file" ]; then
>         mkdir -p -- "$backup_dir/$(dirname -- "$file")"
>         cp --preserve=all -- "$HOME/$file" "$backup_dir/$file"
>     fi
> done
$ printf 'backup: %s\n' "$backup_dir"
backup: /home/YOUR_USER/byobu-launcher-backup-YYYYMMDD-HHMMSS

Keep the printed directory until you have tested a new login. A backup under your home directory may itself be visible to other processes with access to your account, so do not put secrets in these shell files while preparing this change.

3. Choose what detaching should do

By default, the installed utility configures Byobu so that detaching from the session also logs you out. That may be appropriate for a short-lived console login, but it is an easy surprise over SSH: pressing the detach key can end the SSH session instead of leaving you at the remote shell.

To retain the login after detaching, use the documented --no-logout option. The short form is -n. Choose one command, not both.

# Detach from Byobu and also log out (the default)
$ byobu-launcher-install

# Detach from Byobu but keep the login session
$ byobu-launcher-install --no-logout

These commands modify persistent per-user configuration, so do not paste either one into an account you are only borrowing. The installer first removes its previous launcher entries, then adds the current entry. Re-running it is therefore the normal way to switch between the two detach policies, but it still changes your shell startup files.

Checkpoint: inspect the result

After the command returns, inspect the relevant files before opening a new login. The installer appends a launcher line to $HOME/.profile and to writable shell-specific profile files when applicable. It also handles Zsh and Fish in specific circumstances, and creates $HOME/.hushlogin.

$ grep -nF 'byobu-launch' "$HOME/.profile" "$HOME/.bash_profile" "$HOME/.bash_login" "$HOME/.zprofile" 2>/dev/null || true
/home/YOUR_USER/.profile:12:_byobu_sourced=1 . /usr/bin/byobu-launch 2>/dev/null || true
$ ls -l "$HOME/.hushlogin"
-rw-r--r-- 1 YOUR_USER YOUR_USER ... /home/YOUR_USER/.hushlogin

The exact line number, owner display and spacing vary. The launcher path is built from Byobu's configured prefix, normally /usr. If a shell profile already contains unrelated custom code, review the diff rather than assuming every line belongs to Byobu:

$ diff -u "$backup_dir/.profile" "$HOME/.profile" 2>/dev/null || true

If you chose --no-logout, the utility also creates the Byobu flag named no-logout-on-detach in Byobu's per-user configuration directory. The directory is selected by Byobu's own environment and may be under $HOME/.byobu. Check for the flag without guessing its parent:

$ find "$HOME" -maxdepth 3 -type f -name no-logout-on-detach -print 2>/dev/null
/home/YOUR_USER/.byobu/no-logout-on-detach

No output from this last command is expected when you selected the default logout behaviour. Do not create the file by hand just to make the check pass: let the installer manage the setting.

4. Test a fresh login

Startup files are read at login, not necessarily in the shell that is already open. Keep your current session available as a recovery path and open a second SSH connection, or log in on a separate local console. Do not close the only administrative session until the test succeeds.

$ ssh YOUR_USER@YOUR_HOST
$ printf 'login shell: %s\n' "$0"
login shell: -bash

You should see Byobu start on the fresh login, provided the connection is a login and interactive session supported by the installed launcher. If it starts, detach using your configured Byobu key sequence and check the result you selected. With --no-logout, the underlying login should remain available after detaching. With the default, the login may end when Byobu detaches.

If the new session immediately closes or repeatedly launches Byobu, use the original session to inspect the profile diff. A line copied into the wrong startup file, a broken shell command earlier in the file, or an unusual shell can prevent a useful login. The installer does not make Byobu a system-wide service, and elevated privileges will not repair a per-user profile mistake.

5. Undo automatic Byobu startup

Use the matching uninstall utility when you want to stop automatic launching. It removes the launcher configuration installed by Byobu; it does not uninstall the package and does not remove your Byobu sessions.

$ command -v byobu-launcher-uninstall
/usr/bin/byobu-launcher-uninstall
$ byobu-launcher-uninstall

Recheck the profiles after it returns:

$ grep -nF 'byobu-launch' "$HOME/.profile" "$HOME/.bash_profile" "$HOME/.bash_login" "$HOME/.zprofile" 2>/dev/null || true

If you need to restore a complete pre-change file rather than remove only Byobu's entry, copy the specific backup back into place after comparing it first:

$ diff -u "$backup_dir/.profile" "$HOME/.profile"
$ cp --preserve=all -- "$backup_dir/.profile" "$HOME/.profile"

The backup restore is a replacement operation. It can discard edits made after the backup, so use it only when the comparison shows that is what you intend. Keep the current file and make a new backup if other changes need preserving.

Common traps

• Running it with sudo: this targets the root account's home or a changed environment, not necessarily your own login. Use the ordinary user account unless you are intentionally configuring root.
• Testing in the existing shell: a current interactive shell will not reliably replay all login startup files. Use a second login.
• Expecting a system-wide switch: the utility writes per-user files unless the system has a special global Byobu profile link. Other accounts are not configured by your run.
• Confusing silence with failure: the script is quiet when successful. Check its exit status and inspect the files, rather than relying on a success message.
• Overwriting hand-edited profiles: restore only the affected file from a reviewed backup. Do not replace a profile blindly after several unrelated shell changes.