GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
WEMUX(1) WEMUX(1)

wemux - multi-user tmux sessions made easy

Host or join multi-user tmux sessions.

WEMUX HOST COMMANDS
wemux start
wemux attach
wemux stop
wemux users
wemux kick
wemux config
wemux help
WEMUX CLIENT COMMANDS:
wemux mirror
wemux pair
wemux rogue
wemux logout
WEMUX SESSION COMMANDS:
wemux join
wemux reset
wemux list

wemux enhances tmux to make multi-user terminal multiplexing both easier and more powerful. It allows users to host a wemux session and have clients join in either:

Mirror Mode gives clients (another SSH user on your machine) read-only access to the session, allowing them to see you work, or

Pair Mode allows the client and yourself to work in the same terminal (shared cursor) or work independently in another window (separate cursors) in the same tmux session.

It features multi-session support as well as user listing and notifications when users attach/detach.

Start a wemux session, chmod /tmp/wemux-wemux to 1777 so that other users may connect to it, and attach to it. If a wemux session already exists, it will attach to it instead.

Attach to an existing wemux session.

Kill the wemux session and remove the /tmp/wemux-wemux socket.

Kick an SSH user from the server and remove their wemux pair sessions.

Open /usr/local/etc/wemux/wemux.conf in your $EDITOR.

When wemux is run without any arguments in host mode, it is just like running wemux start. It will reattach to an existing wemux session if it exists, otherwise it will start a new session.

Attach to session in read-only mode.

Attach to session in pair mode, which allows editing.

Attach to server in rogue mode, which allows editing and switching to windows independently from the host.

Remove your pair mode session.

When wemux is run without any arguments in client mode, its behavior attempts to intelligently select mirror, pair or rogue:
  • If the client does not have an existing rogue session it will attach to the wemux session in pair mode.
  • If the client has already started a wemux rogue mode session, it will reattach to the session in rogue mode.
  • By setting default_client_mode="rogue" in wemux.conf this can be changed to always join in pair mode, even if a pair session doesn´t already exist.

wemux passes commands it doesn´t understand through to tmux with the correct socket setting.

wemux list-sessions is equivalent to entering tmux -S /tmp/wemux-wemux list-sessions

wemux can display a list of connected users, indicating users in mirror mode with [m] at the end of their name.

If you´d like to see a list of all users currently connected to the wemux session, you have three options:

Enter wemux users in the terminal to display a list of all currently connected wemux users. 
$ wemux users
Users connected to ´wemux´:
  1. zolrath
  2. csagan[m]

You can add the user list to your status bar by adding #(wemux status_users) where you see fit by editing your ~/tmux.conf file. 
set -g status-right "#(wemux status_users)"

If you´d rather display users on command via a tmux message, similar to the user attachment/detachment messages, you can do so by editing your ~/tmux.conf file. Pick whatever key you´d like to bind the displaying the message to. Using t as an example: 
unbind t
bind t run-shell ´wemux display_users´

Note that the tmux prefix should be pressed before t to activate the command.

User listing can be disabled by setting allow_user_list="false" in wemux.conf

All commands have a short form. s for start, a for attach, p for pair etc. For a complete list, type wemux help (or wemux h)

wemux supports specifying the joining different wemux sessions via wemux join <session>. This allows multiple hosts on the same machine to host their own independent wemux sessions with their own clients. By default this option is disabled.

wemux will remember the last session specified to in order to make reconnecting to the same session easy. wemux help will output the currently specified session along with the wemux command list.

Changing sessions can be enabled by setting allow_session_change="true" in /usr/local/etc/wemux/wemux.conf

To change the wemux session run wemux join <session>. The name will be sanitized to contain no spaces or uppercase letters. 
$ wemux join Project X
Changed wemux session from ´wemux´ to ´project-x´
$ wemux start
$ wemux
$ wemux stop
$ wemux reset
Changed wemux session from ´project-x´ to ´wemux´

Join wemux session with specified name. 
$ wemux join rails
Changed wemux session from ´wemux´ to ´rails´

Alternatively, enter the session number displayed next to the session name in wemux list. 
$ wemux j 1
Changed wemux session from ´rails´ to ´project-x´

Join with no argument simply displays the current wemux server, if you´re into that. 
$ wemux join
Current wemux server: wemux

In order to easily return to the default session you can run wemux reset

Joins the default wemux session: wemux (or value of default_session_name in wemux.conf) 
$ wemux reset
Changed wemux session from ´project-x´ to ´wemux´

To list the name of all currently running wemux sessions run wemux list

List all currently active wemux sessions. 
$ wemux list
Currently active wemux sessions:
  1. project-x
  2. rails
  3. wemux    <- current session

wemux join and wemux stop both accept either the name of a session or the number indicated next to the name in wemux list.

Listing sessions can be disabled by setting allow_session_list="false" in /usr/local/etc/wemux/wemux.conf

There are a number of additional options that be configured in /usr/local/etc/wemux/wemux.conf. In most cases the only option that must be changed is the host_list array. To open your wemux configuration file, you can either open /usr/local/etc/wemux/wemux.conf manually or run wemux config An example configuration file is available at $(DOCDIR)/wemux.conf.example.

To have an account act as host, ensure that you have added their username to the /usr/local/etc/wemux/wemux.conf file´s host_list array. 
host_list=(zolrath hostusername brocksamson)

Pair mode can be disabled, only allowing clients to attach to the session in mirror mode by setting allow_pair_mode="false"

Rogue mode can be disabled, only allowing clients to attach to the server in mirror or pair mode by setting allow_rogue_mode="false"

When clients enter ´wemux´ with no arguments by default it will first attempt to join an existing rogue mode session. If there is no rogue session it will start in pair mode. By setting default_client_mode to "rogue", ´wemux´ with no arguments will always join a rogue mode session, even if it has to create it.

This can be changed by setting default_client_mode="rogue"

The default wemux session name will be used with wemux reset and when allow_session_change is not enabled in wemux.conf.

This can be changed by setting default_session_name="customname"

The ability to change sessions can be enabled by setting allow_session_change="true"

Listing sessions can be disabled by setting allow_session_list="false"

Listing users can be disabled by setting allow_user_list="false" in wemux.conf

Kicking SSH users from the server can be disabled by setting allow_kick_user="false" in wemux.conf

When a user joins a session in either mirror or pair mode, a message is displayed to all currently attached users: 
csagan has attached in mirror mode.
csagan has detached.

This can be disabled by setting announce_attach="false"

In addition, when a user switches from one session to another via the wemux join <sessionname> command, their movement is displayed similarly to the attach messages.

If csagan enters wemux join applepie the users on the default session wemux will see:

csagan has switched to session: applepie

If csagan returns to default session with: wemux reset users on wemux will see:

csagan has joined this session.

This can be disabled by setting announce_session_change="false"

To make an SSHed user start in a wemux mode automatically, add one of the following lines to the users .bash_profile or .zshrc

Option 1: Automatically log the client into mirror mode upon login, disconnect them from the server when they detach. wemux mirror; exit

Option 2: Automatically start the client in mirror mode but allow them to detach.
wemux mirror

Option 3: Automatically start the client in pair mode but allow them to detach.
wemux pair

Option 4: Only display the connection commands, don´t automatically start any modes.
wemux help

Please note that this does not ensure a logged in user will not be able to exit tmux and access their shell. If the user is not trusted, you must perform any security measures one would normally perform for a remote user.

March 2014
Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.