Invoking GUI Network tool on Centos 6

 nm-connection-editor

you need to first install NetworkManager using YUM

yum install NetworkManager

Or check it is already started or not

service NetworkManager status

else start the service

service NetworkManager start
chkconfig NetworkManager on

To open to GUI interface you need to execute “nm-applet” command. and to configure or edit configurations “nm-connection-editor” use this command

nm-applet
nm-connection-editor (note: this command is formerly known as system-config-network-gui)

Linux Shell Scripting with Bash(Bash Commands)

bashcommands

Getting Help

The Bash shell comes with a built-in help command to describe the various built-in Bash commands.The -s switch displays a summary for the command you specify.

$ help -s printf
printf: printf format [arguments]

Help only describes Bash commands.To get help on Linux commands, you need to use the man (manual) command.

 $ man date
32 Chapter 3 Files, Users, and Shell Customization

Linux divides its manual pages into a number of logical volumes. man displays any matching entries from any volume.Volume 1 contains the commands you can execute from the shell.To restrict your search to shell commands, use man 1.

 $ man 1 date

If there are pages in more than one manual volume, only the page from the first volume that matches your search is displayed.To find matching pages across all manual volumes, use the -a (all) switch.
The -k switch searches the Linux manual for a particular keyword and lists all man pages referring to that keyword.

 $ man 1 -k alias

The command help type gives you different information than man 1 type.The help type command tells you about Bash’s built-in type command, whereas the man 1 type command tells you about the Linux type command. If you are not sure whether a command is a Bash command, always try the help command before using the man command.

Fixing the Display

There will be times when a Bash session becomes unusable. Certain character sequences can lock your display, hide what you type, or change the characters being shown into strange symbols.This can happen, for example, when you’re trying to display a binary file.

The reset command attempts to restore a Bash session to a safe, sane state. If reset fails, you might also need to use stty sane to restore the session to a normal state. The clear command clears the display and returns the cursor to the upper-left corner.
There are several Linux commands for removing, copying, and moving files. mkdir (make directory) creates a new directory. Use mkdir to organize your files.

$ mkdir prototypes
$ ls -l
total 4
drwxr-xr-x 2 ken users 4096 Jan 24 12:50 prototypes

There are two switches for mkdir:
n –mode=m (-m)—Sets the permission mode (as in chmod)
n –parents (-p)—Makes all necessary directories even if they don’t currently exist

$ mkdir --parents --mode=550 read_only/backup/january
$ ls -l
Working with Files 33
total 4
drwxr-xr-x 2 ken users 4096 Jan 24 12:50 backup
drwxr-xr-x 3 ken users 4096 Jan 24 12:51 read_only
$ ls -l read_only/backup
total 4
dr-xr-x--- 2 ken users 4096 Jan 24 12:51 january

The values for mode are discussed with the chmod command in Chapter 15,“Shell Security.” However, when –parents is used, the –mode affects only the final directory in the list.

rmdir (remove directory) deletes a directory.The directory must be empty before it can be removed.There are two switches: n –ignore-fail-on-non-empty—Doesn’t report an error when it can’t delete a directory with files still in it
n –parents (-p)—Removes all parent directories as well as the subdirectory

 $ rmdir read_only
rmdir: read_only: Directory not empty
$ rmdir --parents read_only/backup/january/

The rm (remove) command permanently deletes files. If the file is a symbolic or hard link, it removes the link but leaves the file intact.

$ rm old_notes.txt
$ ls old_notes.txt
ls: old_notes.txt: No such file or directory

There are several switches for rm:
n –directory (-d)—Removes a directory
n –force (-f)—Never prompts the user and ignores missing files
n –interactive (-i)—Always prompts the user
n –recursive (-r or -R)—Removes contents of all subdirectories

Using the –recursive and –force switches simultaneously removes all the specified files, including all sub directories, without warning. Make sure you are deleting the correct files.

Some Linux distributions have the –interactive switch on by default so that rm requires that you confirm when you want to delete a particular file.

$ rm --interactive old_notes.txt
rm: remove ‘old_notes.txt’? y
$

Normally rm won’t delete a directory, but the –recursive switch deletes any directories encountered.

The cp (copy) command copies files from any location to another. If the final file listed is a directory, copy copies the other files into that directory.

There are many switches for copy—the complete list is in the reference section at the
end of this chapter. Some common switches are as follows:

n –force (-f)—Never prompts the user; always overwrites
n –interactive (-i)—Always prompts user
n –link (-l)—Creates a hard link instead of copying
n –parents (-P)—Appends the source path to destination directory
n –recursive (-R)—Copies any subdirectories
n –symbolic-link (-s)—Creates a symbolic link instead of copying
n –update (-u)—Overwrites old files or copies missing files

$ cp notes.txt old_notes.txt # copying
$ mkdir backup
$ cp old_notes.txt backup
$ ls backup
old_notes.txt

Like rm, some Linux distributions have –interactive on by default, warning when a file will be overwritten.

$ cp --interactive project_notes.txt old_notes
cp: overwrite ‘old_notes/project_notes.txt’? n
$

The mv (move) command moves and renames files.This is the same as making a copy of the file and deleting the original. Move also effectively renames a file by moving it to a new name in the same directory.

$ mv notes.txt project_notes.txt # renaming

The most common mv switches are similar to cp:
n –backup (-b)—Makes a backup of any existing file before overwriting by adding
a ~ to the name
n –force (-f)—Never prompts the user; always overwrites
n –interactive (-i)—Always prompts the user before overwriting
n –update (-u)—Overwrites old files or copies missing files
There is no –recursive switch.When move moves a directory, it moves the directory
and all its contents automatically.

The namei (name inode) command lists all the components in a path, including any symbolic links.

$ namei files
f: files
l files -> /home/geroge/text/scripts
d /
Working with People 35
d home
d geroge
d text
d scripts

In this case, the file named files is a symbolic link. Each of the files in the link path is a directory, marked with a d. Other file designations include l for symbolic link, s for socket, b for block device, c for character device, – for regular file, and ? for an error accessing a file in the path. Complete file permissions, such as seen with ls -l, can be shown with the -m (mode)
switch.

Working with People
There are several commands for checking to see who is on the computer and what they are doing.

The finger command shows who is on the computer and provides additional information, including how long their session has been idle, and their contact information.

$ finger
Login  Name          TTY  Idle    When     Bldg.     Phone
grm   Geroge Malgler  *p6   4:19 Thu 14:06 8th Floor   ext 9703
xel  Xian Lim       *con  6:07 Fri 08:47 Technical   ext 9876
vis  Violet Smith   *p7   10   Fri 17:32

Some versions of Linux no longer include finger because of security concerns over finger’s .plan files. Read the finger manual page for more information.
There are several other commands with similar functions.The users command shows a list of login names.

$ users
grm xel vis

The who command shows who is on the computer, which connection they are using, and when they signed on.

$ who
grm ttyp6 Mar 29 14:12
xel console Apr 6 09:57
vis ttyp7 Apr 6 13:32

The w command provides even more information, including system statistics and what the users are currently running.

$ w
3:18pm up 9 days, 20:33, 3 users, load average: 0.64, 0.66, 0.64
User tty login@ idle JCPU PCPU what
grm ttyp6 2:12pm 4:28 8:01 8:01 csh
xel console 9:57am 5:10 sh
vis ttyp7 1:32pm 19 bash

Linux Shell Scripting with Bash (printf command)

printfcommand

printf Command
The built-in printf (print formatted) command prints a message to the screen. You will use this command a lot in shell scripts. printf is very similar to the C standard I/O printf() function, but they are not identical. In particular, single- and double-quoted strings are treated differently in shell scripts than in C programs.

The first parameter is a format string describing how the items being printed will be represented. For example, the special formatting code “%d” represents an integer number, and the code “%f” represents a floating-point number.

$ printf “%d\n” 5
5
$ printf “%f\n” 5
5.000000

Include a format code for each item you want to print. Each format code is replaced with the appropriate value when printed. Any characters in the format string that are not part of a formatting instruction are treated as printable characters.

 $ printf “There are %d customers with purchases over %d.\n” 50 20000
There are 50 customers with purchases over 20000.

printf is sometimes used to redirect a variable or some unchanging input to a command. For example, suppose all you want to do is pipe a variable to a command. Instead of using printf, Bash provides a shortcut <<< redirection operator. <<< redirects a string into a command as if it were piped using printf.

The tr command can convert text to uppercase. This example shows an error message being converted to uppercase with both printf and <<<.

 $ printf “%s\n” “$ERRMSG” | tr [:lower:] [:upper:]
WARNING: THE FILES FROM THE OHIO OFFICE HAVEN’T ARRIVED.
$ tr [:lower:] [:upper:] <<< “$ERRMSG”
WARNING: THE FILES FROM THE OHIO OFFICE HAVEN’T ARRIVED.

The format codes include the following.
%a—Represent a floating-point number in hexadecimal format, using lowercase
letters
%A—Represent a floating point number in hexadecimal format, using uppercase
letters
%b—Expand backslash sequences
%c—Represent a single character
%d—Display a signed number
%e—Display a floating-point number, shown in exponential (also called “scientific”)
notation
%f (or %F)—Display a floating-point number without exponential notation
%g—(General) Let Bash choose %e or %f, depending on the value
%i—Same as %d
%0—Display an octal number
%q—Quote a string so it can be read properly by a shell script
30 Chapter 3 Files, Users, and Shell Customization
%s—Display an unquoted string
%u—Display an unsigned number
%x—Display an unsigned hexadecimal number, using lowercase letters
%X—Display an unsigned hexadecimal number, using uppercase letters
%%—Display a percent sign

If a number is too large, Bash reports an out-of-range error.

 $ printf “%d\n” 123456789123456789012
bash: printf: warning: 123456789123456789012: Numerical result out of range

For compatibility with C’s printf, Bash also recognizes the following flags, but treats
them the same as %d:
%j—A C intmax_t or uintmax_t integer
%t—A C ptrdiff_t integer
%z—A C size_t or ssize_t integer
Also for C compatibility, you can preface the format codes with a l or L to indicate a long number.

The %q format is important in shell script programming and it is discussed in the  quoting section, in the Chapter 5,“Variables.”

To create reports with neat columns, numbers can proceed many of the formatting codes to indicate the width of a column. For example, “%10d” prints a signed number in a column 10 characters wide.

 $ printf “%10d\n” 11
11

Likewise, a negative number left-justifies the columns.

$ printf “%-10d %-10d\n” 11 12
11 12

A number with a decimal point represents a column width and a minimum number of digits (or decimal places with floating-point values). For example, “%10.5f” indicates a floating-point number in a 10-character column with a minimum of five decimal places.

$ printf “%10.5f\n” 17.2
17.20000

Finally, an apostrophe (‘)displays the number with thousands groupings based on the current country locale.
The \n in the format string is an example of a backslash code for representing unprintable characters. \n indicates a new line should be started. There are special backslash formatting codes for the representation of unprintable characters.

\b—Backspace
\f—Form feed (that is, eject a page on a printer)
\n—Start a new line
\r—Carriage return
\t—Tab
\v—Vertical tab
\’—Single quote character (for compatibility with C)
\\—Backslash
n—n is an octal number representing an 8-bit ASCII character

$ printf “Two separate\nlines\n”
Two separate
Lines

Any 8-bit byte or ASCII character can be represented by or \ and its octal value.

$ printf “ASCII 65 (octal 101) is the character 101\n”
ASCII 65 (octal 101) is the character A

printf recognizes numbers beginning with a zero as octal notation, and numbers beginning with 0x as hexadecimal notation. As a result, printf can convert numbers between these different notations.

 $ printf “%d\n” 010
8
$ printf “%d\n “ 0xF
15
$ printf “0x%X\n “ 15
0xF
$ printf “0%o\n “ 8
010

Linux Shell Scripting with Bash (Listing Files)

lsandrmcommand

Listing Files
The ls (list) command shows the contents of the current directory.

$ ls
archive command_checker.sh commands.txt

ls has switches that affect how the files are listed, including the level of detail, the sorting order, and the number of columns. ls hides files that begin with a period.This is the Linux convention for configuration files, history files, and other files that a user isn’t normally interested in.

To see these files,use the -

A (all) switch. Use -a (absolutely all) to show the implicit . and .. files as well.

 $ ls -A
.bash_history .bash_logout .bash_profile .bashrc archive
command_checker.sh commands.txt

The filenames can be printed in color to show the kind of file they are. The colors are defined in a file /etc/DIR_COLORS. You can customize the colors using a .dir_colors file in your own directory. The format of the file is described in the
/etc/DIR_COLORS file.

To display the files without color and with symbols instead, use the –color and –classify (or -F) switches. (On most Linux distributions, this feature is turned on using aliases.)

$ ls --color=never --classify
archive/ command_checker.sh* commands.txt

The –classify symbols are directories (/), programs (*), symbolic links (@), pipes (|), and Unix domain socket files (=). These symbols are not a part of the name: They are hints as to the type of file. In this example, archive is a directory and command_checker.sh is a program.

Another very important switch is –hide-control-chars (or -q). Linux filenames can contain any character, even control characters. It is possible to create a filename with hidden characters in the name. In these cases, you can’t rename or delete the file unless you know what the hidden characters are. Contrary to what the name implies, the
–hide-control-chars switch displays any unprintable characters in the filename as question marks, making their locations visible.

 $ rm commands.txt 
rm: commands.txt  non-existent
$ ls --color=never --classify –-hide-control-chars
archive/ command_checker.sh* comm?ands.txt

Linux Shell Scripting with Bash

bash-icone1So back to basics. I am trying to do some shell scripting in Linux using Bash. There’s a vast number of commands that you can use that bash can interpret, so i can’t do it in one posting. From time to time i will be posting some commands that i used for bash. So for the meantime here are the basics of bash commands.

 

bashBash Keywords
A keyword is a word or symbol that has a special meaning to a computer language.The
following symbols and words have special meanings to Bash when they are unquoted
and the first word of a command.

                
      !      esac       select            }
      case   fi         then              [[
      do     for        until             ]]
      done   function   while            
      elif   if         time              
      else   in         {

Unlike most computer languages, Bash allows keywords to be used as variable names
even though this can make scripts difficult to read.To keep scripts understandable, keywords
should not be used for variable names.
Command Basics
The commands that can be typed at the Bash shell prompt are usually Linux programs
stored externally on your file system. Some commands are built into the shell for speed,
standardization, or because they can function properly only when they are built-in.

No matter what their source, commands fall into a number of informal categories.
Utilities are general-purpose commands useful in many applications, such as returning the
date or counting the number of lines in a file.
Filters are commands that take the results of one command and modify them in some
way, such as removing unwanted lines or substituting one word for another. Many commands
act as filters under the right circumstances.
To execute a command, type it at the Bash command prompt.The prompt is usually a
$, but often Linux distributions customize it to something else. S.u.S.E., for example, uses
a > command prompt.
The date command prints the current date and time on the screen.

$ date
Wed Apr 4 10:44:52 EDT 2001

All files, including shell commands, are case-sensitive. By convention, all shell commands
are in lowercase.

$ DATE
bash: DATE: command not found

Arguments are additional information supplied to a command to change its behavior.
The date command takes a format argument to change the appearance of the date and
time.

$ date ‘+%H:%M’
10:44

Switches (also called “options” or “flags”) are characters proceeded by a minus sign that
enable command features.To see the date in Coordinated Universal Time (UTC, formerly
called GMT), use the -u switch.

$ date -u
Wed Apr 4 14:46:41 UTC 2001

Because the terms “options” and “flags” are used in so many contexts, they are
referred to as switches in this book.
Switches and arguments are collectively called parameters. Some commands allow any
number of parameters or have parameters that can be arranged in complex ways.
The GNU and Linux convention is for longer, more readable options to be proceeded
by a double minus sign.The longer equivalent to the -u switch is –universal.

$ date --universal
Wed Apr 4 14:46:41 UTC 2001

The long switches remind the reader exactly what the switch does.This makes future
debugging of shell scripts much easier because there is no standard convention for the
short switches across Linux commands. Most Linux commands recognize the long
switches –help, –verbose, and –version.
Command-Line Editing 15
Comments can be added to the end of any command or they can be typed on a line
by themselves. Comments are denoted with a number sign (#).

 $ date --universal # show the date in UTC format

Built-in Bash commands and most other GNU software treat — as a special switch
that indicates the end of a list of switches.This can be used when one of the arguments
starts with a minus sign.
Command-Line Editing

There are special key combinations to edit what you type or to repeat previous commands.
Bash has two editing modes.These modes emulate the keys used in two popular
Linux text editors. Vi mode mimics the vi and vim editors. Emacs mode works like emacs,
nano or pico.

The current editing mode can be checked with the shopt command. shopt -o
emacs is on if you are in emacs mode. shopt -o vi is on if you are in vi mode. Only
one mode can be on at a time.

$ shopt -o emacs
emacs on
$ shopt -o vi
vi off

Regardless of the mode, the arrow keys move the cursor and step through the most
recently executed command:
n Left arrow—Moves back one character to the left. No characters are erased.
n Right arrow—Moves forward one character to the right.
n Up arrow—Moves to the previous command in the command history.
n Down arrow—Moves to the next command in the command history (if any).
Using the left and right arrows, the cursor moves to any position in the command. In
the middle of a line, new text is inserted into the line without overwriting any old
typing.

Emacs mode is the default mode on all the major Linux distributions.The most common
emacs keys are as follows:

n control-b—Moves back one character to the left. No characters are erased.
n control-f—Moves forward one character to the right.
n control-p—Moves to the previous command in the command history.
n control-n—Moves to the next command in the command history (if any).
n Tab key—Finds a matching filename and completes it if there is one exact match.

The filename completion feature attempts to find a matching filename beginning
with the final word on the line. If a matching filename is found, the rest of the filename
is typed in by Bash. For example,
$ dat
is completed when the Tab key is pressed to

 $ date

if date is the only command that can be found starting with the characters dat.
The vi mode key combinations are as follows:
n Esc—Enters/exits editing mode.
n h—Moves back one character to the left. No characters are erased.
n l—Moves forward one character to the right.
n k—Moves to the previous command in the command history.
n j—Moves to the next command in the command history (if any).
n Esc twice—Finds a matching filename and completes it if there is one exact
match.

A complete list of key combinations (or bindings) is listed in the Bash man page in the
Readline section.The default key combinations can be changed, listed, or reassigned
using the bind command.To avoid confusion, it is best to work with the defaults unless
you have a specific application in mind.

Other editing keys are controlled by the older Linux stty (set teletype) command.
Running stty shows the common command keys as well as other information about
your session. Use the -a (all) switch for all settings.

$ stty
speed 9600 baud; evenp hupcl
intr = ^C; erase = ^?; kill = ^X;
eol2 = ^@; swtch = ^@;
susp = ^Z; dsusp = ^Y;
werase = ^W; lnext = ^@;
-inpck -istrip icrnl -ixany ixoff onlcr
-iexten echo echoe echok
-echoctl -echoke

Many of these settings are used only when you’re working with serial port devices
and can be ignored otherwise.The other settings are control key combinations marked
with a caret (^) symbol. Keys with ^@ (or ASCII 0) are not defined.The keys are as follows:
n erase (usually ^?, which is the backspace key on IBM-style keyboards)—Moves
left and erases one character.
n intr (usually ^C)—Interrupts/stops the current program or cancels the current
line.

n kill (usually ^X)—Erases the current line.
Variable Assignments and Displaying Messages 17
n rprnt (usually ^R)—Redraws the current line.
n stop (usually ^S)—Pauses the program so you can read the results on the screen.
n start (usually ^Q)—Resumes the program.
n susp (usually ^Z)—Suspends the current program.
n werase (usually ^W)—Erases the last word typed.
To change the suspend character to control-v, type
$ stty susp ‘^v’

Changing key combinations can be very difficult. For example, if you are running an
X Windows server (the software that runs on a client computer) on a Microsoft Windows
computer to access a Linux computer, key combinations can be affected by the
following:

n Microsoft Windows
n The X server software
n The Linux window manager
n The stty settings
Each acts like layers of an onion and they must all be in agreement. For example,
shift-insert, often used to paste text, might be handled by your X Window server before
your Linux computer or your shell have a chance to see it.
Variable Assignments and Displaying Messages
Variables can be created and assigned text using an equals sign. Surround the text with
double quotes.

$ FILENAME=”info.txt”

The value of variables can be printed using the printf command. printf has two
arguments: a formatting code, and the variable to display. For simple variables, the formatting
code is “%s\n” and the variable name should appear in double quotes with a
dollar sign in front of the name

$ printf “%s\n” “$FILENAME” 
info.txt

printf can also display simple messages. Put the message in the place of the formatting
code.

 $ printf “Bash is a great shell.\n”

Bash is a great shell.

printf and variables play an important role in shell scripting and they are described
in greater detail in the chapters to come.
18 Chapter 2 Operating the Shell
The results of a command can be assigned to a variable using backquotes.

$ DATE=`date`
$ printf “%s\n” “$DATE”
Wed Feb 13 15:36:41 EST 2002

The date shown is the date when the variable DATE is assigned its value.The value of
the variable remains the same until a new value is assigned.

$ printf “%s\n” “$DATE”
Wed Feb 13 15:36:41 EST 2002
$ DATE=`date`
$ printf “%s\n” “$DATE”
Wed Feb 13 15:36:48 EST 2002

Multiple Commands
Multiple commands can be combined on a single line. How they are executed depends
on what symbols separate them.
If each command is separated by a semicolon, the commands are executed consecutively,
one after another.

$ printf “%s\n” “This is executed” ; printf “%s\n” “And so is this”
This is executed
And so is this

If each command is separated by a double ampersand (&&), the commands are executed
until one of them fails or until all the commands are executed.

$ date && printf “%s\n” “The date command was successful”
Wed Aug 15 14:36:32 EDT 2001 
The date command was successful

If each command is separated by a double vertical bar (||), the commands are executed
as long as each one fails until all the commands are executed.

$ date ‘duck!’ || printf “%s\n” “The date command failed”
date: bad conversion
The date command failed

Semicolons, double ampersands, and double vertical bars can be freely mixed in a single
line.

 $ date ‘format-this!’ || printf “%s\n” “The date command failed” && \
printf “%s\n” “But the printf didn’t!”
date: bad conversion
The date command failed
But the printf didn’t!

These are primarily intended as command-line shortcuts:When mixed with redirection
operators such as >, a long command chain is difficult to read and you should avoid
it in scripts.

Command History 19
Command History

Bash keeps a list of the most recently typed commands.This list is the command history.
The easiest way to browse the command history is with the Up and Down arrow
keys.The history can also be searched with an exclamation mark (!).This denotes the
start of a command name to be completed by Bash. Bash executes the most recent command
that matches. For example,

$ date
Wed Apr 4 11:55:58 EDT 2001
$ !d
Wed Apr 4 11:55:58 EDT 2001

If there is no matching command, Bash replies with an event not found error
message.

$ !x
bash: !x: event not found

A double ! repeats the last command.

$ date
Thu Jul 5 14:03:25 EDT 2001
$ !!
date
Thu Jul 5 14:03:28 EDT 2001

There are many variations of the ! command to provide shortcuts in specific situations.
A negative number indicates the relative line number.That is, it indicates the number
of commands to move back in the history to find the one to execute. !! is the same as
!-1.

$ date
Thu Jul 5 14:04:54 EDT 2001
$ printf “%s\n” $PWD
/home/kburtch/
$ !-2
date
Thu Jul 5 14:05:15 EDT 2001

The !# repeats the content of the current command line. (Don’t confuse this with #!
in shell scripts.) Use this to run a set of commands twice.

 $ date ; sleep 5 ; !#
date ; sleep 5 ; date ; sleep 5 ;
Fri Jan 18 15:26:54 EST 2002
Fri Jan 18 15:26:59 EST 2002
20 Chapter 2 Operating the Shell

Bash keeps the command history in a file called .bash_history unless a variable
called HISTFILE is defined. Each time you quit a Bash session, Bash saves the history of
your session to the history file. If the histappend shell option is on, the history is
appended to the old history up to the maximum allowed size of the history file. Each
time you start a Bash session, the history is loaded again from the file.
Another shell option, histverify, enables you to edit the command after it’s
retrieved instead of executing it immediately.

Bash has a built-in command, history, which gives full control over the command
history.The history command with no parameters lists the command history. If you
don’t want to see the entire history, specify the number of command lines to show.

$ history 10
1026 set -o emacs
1027 stty
1028 man stty
1029 stty -a
1030 date edhhh
1031 date edhhh
1032 date
1033 date
1034 !
1035 history 10

You can test which command will be matched during a history completion using the
-p switch.

$ history -p !d
history -p date
date

A particular command line can be referred to by the line number.

$ !1133
date
Thu Jul 5 14:09:05 EDT 2001

history -d deletes an entry in the history.

$ history -d 1029
$ history 10
1027 stty
1028 man stty
1029 date edhhh
1030 date edhhh
1031 date
1032 date
1033 !
1034 history 10
1035 history -d 1029
1036 history 10
Directory Commands 21

The -s switch adds new history entries. -w (write) and -r (read) save or load the history
from a file, respectively.The -a (append) switch appends the current session history to
the history file.This is done automatically when you quit the shell.The -n switch loads
the complete history from the history file. history -c (clear) deletes the entire history.
The command history can be searched with !? for the most recent command containing
the text. If there is additional typing after the !? search, the command fragment
will be delineated with a trailing ?.

$ date
Thu Jul 5 14:12:33 EDT 2001
$ !?ate
date
Thu Jul 5 14:12:38 EDT 2001
$ !?da? ‘+%Y’
date ‘+%Y’
2001

The quick substitution history command, ^, runs the last command again, replacing
one string with another.

$ date ‘+%Y’
2001
$ ^%Y^%m^
date ‘+%m’
07

The Bash history can be turned off by unsetting the -o history shell option.The
cmdhist option saves multiple line commands in the history.The lithist option breaks
up commands separated by semicolons into separate lines.
Directory Commands
The built-in pwd (present working directory) command returns the name of your current
directory.

$ pwd
/home/dsmith

Although you might not think such a simple command needs options, pwd has a couple
of switches.The -P (physical) switchshows the actual directory, whereas the default -L
(logical) switch shows the directory, including any symbolic links. For example, if /home
was a link to a directory called /user_drive/homes, the switches work as follows:

$ pwd -P
/user_drive/homes/dsmith
$ pwd -L
/home/dsmith
22 Chapter 2 Operating the Shell

The built-in cd (change directory) command changes your current directory. As discussed
in Chapter 1,“The Linux Environment,” the special directory .. represents the
parent directory, whereas . represents the current directory.

$ pwd
/home/dsmith
$ cd .
$ pwd
/home/kburtch
$ cd ..
$ pwd
/home
$ cd dsmith
$ pwd
/home/dsmith

Each time you change the directory, Bash updates the variable PWD containing the
path to your current working directory. Bash also maintains a second variable called OLDPWD
that contains the last directory you were in.
Using the minus sign (–) with cd, you can switch between the current directory and
the last directory.This is a useful shortcut if you are doing work in two different directories.

$ pwd
/home/dsmith
$ cd ..
$ pwd
/home
$ cd -
$ pwd
/home/dsmith
$ cd -
$ pwd
/home

The tilde (~) represents your current directory. Use it to move to a directory relative
to your home directory.To move to a directory called mail in your home directory, type

$ cd ~/mail

Although . and .. work in all Linux programs, ~ and – are features of Bash and only
work with Bash and Bash scripts.

cd by itself returns you to your home directory, the same as cd ~.
If a CDPATH variable exists, it is assumed to contain a list of directories similar to the
PATH variable.This is a throwback to the days when a user was only able to use one shell
session on his terminal and is now considered a security risk. Its use should be avoided.

Specialized Navigation and History 23
Specialized Navigation and History

Because most users can open multiple shell sessions, there is little need for complex
movement between directories. cd – switches between two directories, which is suitable
for most circumstances. However, if you are restricted to a single shell session and want
Bash to remember more directories, there are three built-in commands that maintain a
list of directories.

The built-in dirs command shows the list of saved directories.The current directory
is always the first item in the list.

$ dirs

~
The built-in pushd (push directory) command adds (or pushes) directories onto the list
and changes the current directory to the new directory.

 $ pushd /home/dsmith/invoices
~/invoices ~ 
$ pushd /home/dsmith/work
~/work ~/invoices ~
$ pwd
/home/dsmith/work

There are now three directories in the list.
The -n (no change) switch will put a directory into the list without changing directories.
-N (rotate Nth) moves the nth directory from the left (or, with +N, from the right) to
the top of the list.
The dirs -l switch displays the directory names without any short forms.

$ dirs -l
/home/dsmith/work /home/dsmith/invoices /home/dsmith

The -v switchdisplays the list as a single column, and -p shows the same information
without the list position.The -c switch clears the list.The -N (view Nth) shows the nth
directory from the left (or, with +N, from the right).

$ dirs +1
~

The built-in popd (pop directory) command is the opposite of the pushd. popd discards
the first directory and moves to the next directory in the list.

 $ popd
~/invoices ~
$ pwd
/home/dsmith/invoices

The switches for popd are similar to pushd: -n to pop without moving, and -N to
delete the Nth entry from the left (or, with +N, the right).
24 Chapter 2 Operating the Shell
The Colon Command
The simplest shell command is the colon (:).This is the colon command (sometimes called
a “no-op” or “null command”) and does nothing.What’s the use of a command that
does nothing? There are some places in shell programs where a statement is required. In
those cases, you can use : to indicate nothing special should be done.
At the command prompt, : has no effect.

$ :
$

The colon command can have parameters and file redirections.This can have strange
effects, such as running the date command using backquotes, giving the results to the
null command that quietly discards them.

$ : `date`
$

This has the same effect as redirecting the output of date to the /dev/null file.

$ date > /dev/null

 

date Command Switches
n –date=s (or -d s)—Displays time described by s.
n –file=f (or -f f)—Displays times listed in file f.
n –iso-8601=t (or -I t)—Displays an ISO-8601 standard time.
n –reference=f (or -r f)—Displays last modification date of file.
n –rfc-822 (or -R)—Uses RFC-822 format.
n –universal (or –utc or -u)—Uses Coordinated Universal Time.

stty Command Switches
n –all (or -a)—Displays all stty settings.
n –save (or -g)—Displays settings so they can be used as parameters to stty.
n –file=d (or -F d)—Opens tty device d instead of stdin.

history Command Switches
n -a—Appends to history file.
n -c—Clears history.
n -d—Deletes history entry.
n -n—Loads from history file.
n -p—Performs history lookup/substitution.
n -r—Reads history from a file.
n -s—Adds new history entries.

pwd Command Switches

n -P—Physical directory
n -L—Logical directory

dirs Command Switches
n -c—Clears all entries
n -l—Shows a long listing (no tildes)
n -p—Lists the entries
n -v—Shows a verbose listing

Terminator for Linux (a very good substitute for terminal)

Terminator

Terminator is a cross-platform GPL terminal emulator with advanced features not yet found elsewhere.

Terminator will run on any modern OS with Java 6 or later. It replaces xterm, rxvt, xwsh and friends on X11 systems, GNOME Terminal, KDE’s Konsole, Apple’s Terminal.app, and PuTTY on MS Windows.

[ ChangeLog | Download | FAQ | Report a Problem | Manual ]

Features

Here are some of the features unique to Terminator, or which are rare amongst the competition:

  • Automatic Logging – Complete logs are automatically generated of all your terminal sessions [full details].
  • Drag & Drop – Text and URLs, and even files from Finder/Nautilus/Windows Explorer can be dropped on Terminator to be inserted as text, with automatic quoting of filenames containing shell meta-characters.
  • Find – Terminator provides you with a find function so you can search for text and regular expressions within your terminal (including the scrollback), highlighting them all, in the style of less(1), and offering quick movement to the next or previous match [full details]. As far as we know, the only other terminal emulator with a find function is Apple’s Terminal, and ours is better.Searches stay active until you cancel them, so if you’re waiting for some particular output in a great stream of output, this is a really great way to make it blindingly obvious when it appears.
    • Freedom – Terminator is released under the GPL.
    • Horizontal Scrolling – Most terminal emulators wrap text when it intrudes upon the right margin. Terminator doesn’t — it instead provides a horizontal scrollbar when necessary (hold down shift to make your scroll wheel scroll horizontally). This brings clear benefits in terms of readability of program output, or text files sent to the display with cat(1). (We tried both this and Apple-like reflowing of text when you change the window size, and we decided we preferred this. Sadly, we don’t have the resources to support two implementations, so reflowing is no longer an option; it’s gone from the code.)
    • Multiple Tabs – Like tabbed browsing, only with terminals [full details].
    • Number Reinterpretation – Terminator will recognize numbers in a variety of bases as the current selection, and add informational menu items to the pop-up menu showing the same number in other bases. No more man ascii or resorting to bc(1).
    • Open Terminator Here – Start a new terminal window in the directory you clicked on in Windows Explorer.
    • Portability- Written mostly in Java, with a small POSIX C++ part (for pseudo-terminal support) and a Ruby invocation script, Terminator should compile out of the box on most modern desktop operating systems. (Pre-built packages are available for most systems, so you don’t need to worry about this.)Now you can use the same great terminal emulator everywhere!
    • Proper Tab Character Handling – Most terminal emulators will translate tab characters into strings of spaces, which is very annoying if you then try to copy/paste a section of text from your terminal into a text editor. Terminator handles tabs properly, remembering where the tabs are and copy/pasting them as tab characters.
    • Unlimited Scrollback – Terminator won’t throw away output when it scrolls off the top of the screen, nor when it reaches any arbitrary limit. You decide when, if ever, to clear the scrollback. (Even if you do clear the scrollback, you can still find lost text in the log, unless you turned that off too.)
    • Intelligent Vertical Scrolling – Terminator’s scrollbar won’t keep jumping when there’s output if you’ve deliberately scrolled back to look at part of the history, but as soon as you scroll back to the bottom again, it will resume auto-scrolling. This gives you the best of both worlds without having to choose up-front via some configuration mechanism.
    • Fewer Gotchas- Terminator automatically turns off XON/XOFF flow control for terminal output. Being able to pause output by typing ^S and resume it by typing ^Q is much less useful given unlimited scrollback and intelligent vertical scrolling, and mainly leads to confusion when it’s accidentally typed by someone who doesn’t know about this functionality (or doesn’t realize they’ve activated it). Turning off XON/XOFF allows Bash and Emacs, amongst others, to make use of these keystrokes.A user who wants the XON/XOFF behavior – perhaps because they like to pause the output from commands like top(1) – can use stty ixon in their login script to re-enable it. Sadly, we can’t just visibly indicate when ^S has stopped output, and provide help in re-starting output, because there’s no way to read this aspect of tty state.
    • Safe Quit- Terminator knows when you still have processes running, and brings up a dialog rather than just letting those processes die.

      Documentation

      Documentation for all of Terminator’s keybindings and config options in man pages is included in the source/packages. See:

      man terminator
      man terminator_config

      Bugs/problems

      Please report all bugs on Launchpad Bugs.

      Installation

      Linux Distributions

      Ubuntu

      Click here: Install Terminator
      This may give you an older version, so to install the very latest Terminator:
      sudo add-apt-repository ppa:gnome-terminator
      sudo apt-get update
      sudo apt-get install terminator
      Thanks to Nicolas Valcarcel for his fantastic work in pushing Terminator into Debian and Ubuntu

      Debian

      If you are running Debian sid then you should find the latest version, although it may be slightly behind the current release.

      Fedora

      To install Terminator in Fedora, run (as root):
      yum install terminator

      Foresight

      To install Terminator in Foresight Linux, you can either use the Add/Remove program (PackageKit), or the following command:
      sudo conary update terminator

      OpenSuSE

      There is something here, but not being an OpenSuSE user I don’t really understand how their package repositories work. Please let me know if there’s something more useful I can write here!

      Mandriva

      If you wish to install Terminator on Mandriva Linux, make sure that the package management system is configured to download packages from Mandriva’s contrib/release and contrib/backports repositories; then run (as root):
      urpmi terminator

      RHEL

      Packages for RHEL5 and 6 are in RPMForge. Instructions for adding this repository are available here. After you’ve done that, you can just run:
      yum install terminator

      Slackware

      There is a SlackBuild for Terminator available here. For more information on using SlackBuilds, see the HowTo.

      FreeBSD

      To install Terminator in FreeBSD, run:
      cd /usr/ports/x11/terminator && make install clean, or portinstall terminator, or pkg_add -r terminator
      See this page for more information.

      Mac OS X

      To install Terminator on Mac OS X you will need to be using the Fink project, and have it configured to allow unstable software. With those requirements satisfied, in a terminal run:
      fink install terminator

      Source

      Version 0.96 can be downloaded from Launchpad
      Older versions can be found here.

      Development

      The development branch is published on Launchpad Code.
      The main Launchpad page for Terminator is here

Split and join large files in GNU/Linux just using command-line(Never knew we could do it on CLI)

To split a large file into smaller ones:

Lets say you have to send your personal video file of size 100MB to your friend through Gmail but gmail has a maximum file upload limit of size 20MB.So you have to split it into 5 smaller files of size 20MB and upload it.For this you have to go to the directory where the file is stored and use the following command in the terminal:

$ split –b20m Largefilename Smallfilename

where 20m is the size of output file in MB,to split in KB put k instead of m.various other options are also available to split command,to know them just type

$ split –help

To join smaller files into a larger one:

These days most files hosted at major file hosting sites are split into smaller files such as *.001…009 or *.part01…*.part09 etc.To join these files you don’t have to search for any external softwares,you just have the commands built into every GNU/Linux system.

To join the part files open up the terminal and navigate to the directory where the files are placed and execute the command:

$ cat partfilename* > outputfilename

For example if the file names are

video.avi.01

video.avi.02

video.avi.03 etc.use

$ cat video.avi.* > video1.avi

Commands on IRC Weechat (CLI IRC Client tool)

WeeChat (Wee Enhanced Environment for Chat) is a console IRC client, which is fast and light. It is released under the terms of the GNU General Public License 3 and has been developed since 2003. There is also a GTK+ interface available and a Qt interface planned.[3]

Everything can be done with a keyboard. It is customizable and extensible with plugins and scripts.

WeeChat 0.2.6 – User guide
Fast, light and extensible IRC client
Sébastien Helleu

Copyright © 2007 Sébastien Helleu

This manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see .

2007-09-06 10:44:50

Abstract

This manual documents WeeChat IRC client, it is part of WeeChat.

Latest version of this document can be found on this page: http://weechat.flashtux.org/doc.php

Table of Contents

1. Introduction

Description
Pre-requisites

2. Installation

Binary packages
Source package
CVS sources

3. Usage

Running WeeChat
Key bindings
Command line
WeeChat / IRC commands

WeeChat commands
Key functions
IRC commands

Configuration file
FIFO pipe

4. Plugins

Plugins in WeeChat
Write a plugin

API functions
Compile plugin
Load plugin into WeeChat
Plugin example

Charset plugin

Settings
FAQ

Scripts plugins

Load / unload scripts
Syntax by language
WeeChat / scripts API

5. Authors / Support

Authors
Contributors
Get support

Chapter 1. Introduction

Table of Contents

Description
Pre-requisites

This chapter describes WeeChat and pre-requisites for its installation.
Description

WeeChat (Wee Enhanced Environment for Chat) is a free IRC client, fast and light, designed for many operating systems.

Main features are:

*

multi-servers connection (with SSL, IPv6, proxy)
*

many GUI: Curses, wxWidgets, Gtk and Qt
*

small, fast and light
*

customizable and extensible with plugins and scripts
*

compliant with RFCs 1459, 2810, 2811, 2812 and 2813
*

multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other)
*

100% GPL, free software

WeeChat homepage is here: http://weechat.flashtux.org
Pre-requisites

In order to install WeeChat, you need:

*

a running GNU/Linux system (with compiler tools for source package)
*

“root” privileges (to install WeeChat)
*

according to GUI, one of the following libraries:
o

Curses: ncurses library
o

Gtk: *** GUI not developed ***
o

WxWidgets: *** GUI not developed ***
o

Qt: *** GUI not developed ***

Chapter 2. Installation

Table of Contents

Binary packages
Source package
CVS sources

This chapter explains how to install WeeChat.
Binary packages

Binary packages are available for these distributions:

*

Debian (or any Debian compatible distribution): apt-get install weechat
*

Mandriva/RedHat (or any RPM compatible distribution): rpm -i /chemin/weechat-x.y.z-1.i386.rpm
*

Gentoo : emerge weechat

For other distributions, please look at your manual for installation instructions.
Source package

All you have to do is to run in a console or a terminal:

$ ./configure
$ make

Then get root privileges and install WeeChat:

$ su
(enter root password)
# make install

CVS sources

Warning: CVS sources are for advanced users: it may not compile or not be stable. You’re warned!

To get CVS sources, issue this command:

$ cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/weechat co weechat

Execute this script: ./autogen.sh

Then follow instructions for source package (see the section called “Source package”)
Chapter 3. Usage

Table of Contents

Running WeeChat
Key bindings
Command line
WeeChat / IRC commands

WeeChat commands
Key functions
IRC commands

Configuration file
FIFO pipe

This chapter explains how to run WeeChat, the default key bindings used, internal and IRC commands, setup file, and FIFO pipe use.
Running WeeChat

Command line arguments:
Parameter     Description
-a, –no-connect     Disable auto-connect to servers at startup
-c, –config     Display config help (list of options)
-d, –dir     Set path as home for WeeChat (used for configuration files, logs, user plugins and scripts). Default value is “~/.weechat”. Please note that directory is created if not found by WeeChat.
-f, –key-functions     Display WeeChat internal functions for keys
-h, –help     Display help
-i, –irc-commands     Display IRC commands list
-k, –keys     Display WeeChat default keys
-l, –license     Display WeeChat license
-p, –no-plugin     Disable plugins auto-load
-v, –version     Display WeeChat version
-w, –weechat-commands     Display WeeChat commands list

It is also possible to give URL for one or many IRC servers, as follow:

irc[6][s]://[pseudo[:mot_passe]@]irc.example.org[:port][/channel][,channel[...]

Example to join #weechat and #toto on “irc.freenode.net” server, default port (6667), with “nono” nick:

$ weechat-curses irc://nono@irc.freenode.net/#weechat,#toto

To start WeeChat, issue this command:

*

for Curses GUI: weechat-curses
*

for Gtk GUI: weechat-gtk
*

for wxWidgets GUI: weechat-wxwidgets
*

for Qt GUI: weechat-qt

When you run WeeChat for the first time, a default configuration file is created, with default options. The default configuration file is: “~/.weechat/weechat.rc”

You can edit this file at your convenience to configure WeeChat (ONLY if WeeChat is not running), or you can set parameters with “/set” command in WeeChat (see the section called “WeeChat commands”)
Key bindings

Key     Action
Left arrow / Ctrl + B     Go to previous char in command line
Right arrow / Ctrl + F     Go to next char in command line
Ctrl + left arrow     Go to previous word in command line
Ctrl + right arrow     Go to next word in command line
Home / Ctrl + A     Go to the beginning of command line
Ctrl + C then B     Insert code for bold text.
Ctrl + C then C     Insert code for colored text.
Ctrl + C then O     Insert code for color reset.
Ctrl + C then R     Insert code for reverse color.
Ctrl + C then U     Insert code for underlined text.
End / Ctrl + E     Go to the end of command line
Ctrl + K     Delete from cursor until end of command line
Ctrl + L     Redraw whole window
Ctrl + R     Search for text in buffer history (two times: search exact text)
Ctrl + S then Ctrl + U     Set unread marker on all buffers
Ctrl + T     Transpose chars
Ctrl + U     Delete from cursor until beginning of command line
Ctrl + W     Delete previous word of command line
Ctrl + Y     Paste clipboard content
Backspace / Ctrl + H     Delete previous char in command line
Delete / Ctrl + D     Delete next char in command line
Tab / Shift + Tab     Complete command or nick (Tab again: find next completion)
Any char     Insert char at cursor position in command line
Enter / Ctrl + J / Ctrl + M     Execute command or send message (in search mode: stop search)
Up arrow / Down arrow     Call again last commands/messages (in search mode: search up/down)
Ctrl + up arrow / Ctrl + down arrow     Call again last commands/messages in global history (common for all buffers)
PageUp / PageDown     Scroll up / down one page in buffer history
Alt + PageUp / Alt + PageDown     Scroll up / down a few lines in buffer history
Alt + Home / Alt + End     Scroll to top / bottom of buffer
F5 / Alt + left arrow     Switch to previous buffer
F6 / Alt + right arrow     Switch to next buffer
F7     Switch to previous window
F8     Switch to next window
F9 / F10     Scroll topic
F11 / F12     Scroll nicklist
Alt + F11 / Alt + F12     Go to the beginning / the end of nicklist
Alt + A     Switch to next buffer with activity (with priority: highlight, message, other)
Alt + B     Go to previous word in command line
Alt + D     Delete next word in command line
Alt + F     Go to next word in command line
Alt + H     Clear hotlist (activity notification on other buffers)
Alt + I     Remove last infobar message
Alt + J then Alt + D     Display DCC buffer
Alt + J then Alt + L     Switch to last buffer
Alt + J then Alt + P     Switch to buffer previously displayed
Alt + J then Alt + R     Switch to raw IRC data buffer
Alt + J then Alt + S     Switch to server buffer
Alt + J then Alt + X     Switch to first channel of next server (or server buffer if no channel is opened)
Alt + digit (0-9)     Switch to buffer by number (0 = 10)
Alt + J then number (01-99)     Switch to buffer by number
Alt + K     Grab a key and insert its code in command line
Alt + N     Scroll to next highlight
Alt + P     Scroll to previous highlight
Alt + R     Delete entire command line
Alt + S     Switch servers on servers buffer (if option “look_one_server_buffer” is enabled)
Alt + U     Scroll to first unread line in buffer
Alt + W then Alt + arrow     Switch to window with direction

Command line

WeeChat command line (at the bottom of window) lets you send text on channels and execute WeeChat or IRC commands (see the section called “WeeChat / IRC commands”).

Commands begin with “/” char, followed by name of command. For example, to initiate a private chat with “toto”:

/query toto

Text sent to a channel is any text that does not begin with “/” char. For example, to send text “hello” on current channel:

hello

However, it is possible to start with “/” char, by adding another. For example, to send text “/query toto” on current channel:

//query toto

If option for sending IRC colors (“irc_colors_send”) is enabled, you can use color codes and attributes, as follow (press Ctrl-C then following letter, with optional value):
Code     Description
^Cb     bold text
^Ccxx     text color “xx” (see colors table below)
^Ccxx,yy     text color “xx” and background “yy” (see colors table below)
^Co     disable color and attributes
^Cr     reverse video (revert text color with background)
^Cu     underlined text

Note: the same code (without number for ^Cc) may be used to stop the attribute.

Color codes for ^Cc are:
Code     Color
00     white
01     black
02     dark blue
03     dark green
04     light red
05     dark red
06     magenta
07     orange
08     yellow
09     light green
10     cyan
11     light cyan
12     light blue
13     light magenta
14     gray
15     light gray (white)

Example: display of “hello everybody!” with “hello” in light blue bold, and “everybody” in light red underlined:

^Cc12^Cbhello^Cb^Cc04^Cu everybody^Cu^Cc!

WeeChat / IRC commands

WeeChat commands
Key functions
IRC commands

This chapter lists all WeeChat and IRC commands.
WeeChat commands

alias [alias_name [command [arguments]]]

create an alias for a command

alias_name: name of alias
command: command name (WeeChat or IRC command, many commands can be separated by semicolons)
arguments: arguments for command

is replaced by all arguments.

Variables $nick, $channel and $server are replaced by current nick/channel/server.

buffer [action [args] | number | [[server] [channel]]]

manage buffers

action: action to do:
move: move buffer in the list (may be relative, for example -1)
close: close buffer (optional arg is part message, for a channel)
list: list open buffers (no parameter implies this list)
notify: set notify level for buffer (0=never, 1=highlight, 2=1+msg, 3=2+join/part)
(when executed on server buffer, this sets default notify level for whole server)
scroll: scroll in history (may be relative, and may end by a letter: s=sec, m=min, h=hour, d=day, M=month, y=year); if there is only letter, then scroll to beginning of this item

number: jump to buffer by number
server,
channel: jump to buffer by server and/or channel name

Examples:
move buffer: /buffer move 5
close buffer: /buffer close this is part msg
set notify: /buffer notify 2
scroll 1 day up: /buffer scroll 1d  ==  /buffer scroll -1d  ==  /buffer scroll -24h
scroll to beginning
of this day: /buffer scroll d
scroll 15 min down: /buffer scroll +15m
scroll 20 msgs up: /buffer scroll -20
jump to #weechat: /buffer #weechat

builtin command

launch WeeChat/IRC builtin command (do not look at plugins handlers or aliases)

command: command to execute (a ‘/’ is automatically added if not found at beginning of command)

clear [-all | number [number ...]]

clear window(s)

-all: clear all buffers
number: clear buffer by number

connect [-all [-nojoin] | servername [servername ...] [-nojoin] | hostname [-port port] [-ipv6] [-ssl]]

connect to server(s)

-all: connect to all servers
servername: internal server name to connect
-nojoin: do not join any channel (even if autojoin is enabled on server)
hostname: hostname to connect, creating temporary server
port: port for server (integer, default is 6667)
ipv6: use IPv6 protocol
ssl: use SSL protocol

disconnect [-all | servername [servername ...]]

disconnect from server(s)

-all: disconnect from all servers
servername: server name to disconnect

dcc action [nickname [file]]

starts DCC (file or chat) or close chat

action: ‘send’ (file) or ‘chat’ or ‘close’ (chat)
nickname: nickname to send file or chat
file: filename (on local host)

debug dump | buffer | windows

print debug messages

dump: save memory dump in WeeChat log file (same dump is written when WeeChat crashes)
buffer: dump buffer content with hexadecimal values in log file
windows: display windows tree

help [command]

display help about commands

command: name of a WeeChat or IRC command

history [clear | value]

show buffer command history

clear: clear history
value: number of history entries to show

ignore [mask [[type | command] [channel [server]]]]

ignore IRC messages and/or hosts

mask: nick or host mask to ignore
type: type of message to ignore (action, ctcp, dcc, pv)
command: IRC command
channel: name of channel for ignore
server: name of server for ignore

For each argument, ‘*’ means all.
Without argument, /ignore command lists all defined ignore.

key [key [function/command]] [unbind key] [functions] [call function ["args"]] [reset -yes]

bind/unbind keys

key: display or bind this key to an internal function or a command (beginning by “/”)
unbind: unbind a key
functions: list internal functions for key bindings
call: call a function by name (with optional arguments)
reset: restore bindings to the default values and delete ALL personal bindings (use carefully!)

plugin [list [name]] | [listfull [name]] | [load filename] | [autoload] | [reload [name]] | [unload [name]]

list/load/unload plugins

list: list loaded plugins
listfull: list loaded plugins with detailed info for each plugin
load: load a plugin
autoload: autoload plugins in system or user directory
reload: reload one plugin (if no name given, unload all plugins, then autoload plugins)
unload: unload one or all plugins

Without argument, /plugin command lists loaded plugins.

reconnect [-all [-nojoin] | servername [servername ...] [-nojoin]]

reconnect to server(s)

-all: reconnect to all servers
servername: server name to reconnect
-nojoin: do not join any channel (even if autojoin is enabled on server)

save [file]

save config to disk

file: filename for writing config

server [list [servername]] | [listfull [servername]] | [add servername hostname [-port port] [-temp] [-auto | -noauto] [-ipv6] [-ssl] [-pwd password] [-nicks nick1 nick2 nick3] [-username username] [-realname realname] [-command command] [-autojoin channel[,channel]] ] | [copy servername newservername] | [rename servername newservername] | [keep servername] | [del servername]

list, add or remove servers

list: list servers (no parameter implies this list)
listfull: list servers with detailed info for each server
add: create a new server
servername: server name, for internal and display use
hostname: name or IP address of server
port: port for server (integer, default is 6667)
temp: create temporary server (not saved in config file)
auto: automatically connect to server when WeeChat starts
noauto: do not connect to server when WeeChat starts (default)
ipv6: use IPv6 protocol
ssl: use SSL protocol
password: password for server
nick1: first nick for server
nick2: alternate nick for server
nick3: second alternate nick for server
username: user name
realname: real name of user
copy: duplicate a server
rename: rename a server
keep: keep server in config file (for temporary servers only)
del: delete a server
deloutq: delete messages out queue for all servers (all messages WeeChat is currently sending)

set [option [ = value]]

set config options

option: name of an option (if name is full and no value is given, then help is displayed on option)
value: value for option

Option may be: servername.server_xxx where “servername” is an internal server name and “xxx” an option for this server.

setp [option [ = value]]

set plugin config options

option: name of a plugin option
value: value for option

Option is format: plugin.option, example: perl.myscript.item1

unalias alias_name

remove an alias

alias_name: name of alias to remove

unignore [number | [mask [[type | command] [channel [server]]]]]

unignore IRC messages and/or hosts

number: # of ignore to unignore (number is displayed by list of ignore)
mask: nick or host mask to unignore
type: type of message to unignore (action, ctcp, dcc, pv)
command: IRC command
channel: name of channel for unignore
server: name of server for unignore

For each argument, ‘*’ means all.
Without argument, /unignore command lists all defined ignore.

upgrade [path_to_binary]

upgrade WeeChat without disconnecting from servers

path_to_binary: path to WeeChat binary (default is current binary)

This command run again a WeeChat binary, so it should have been compiled or installed with a package manager before running this command.

uptime [-o]

show WeeChat uptime

-o: send uptime on current channel as an IRC message

window [list | -1 | +1 | b# | up | down | left | right | splith [pct] | splitv [pct] | resize pct | merge [all]]

manage windows

list: list open windows (no parameter implies this list)
-1: jump to previous window
+1: jump to next window
b#: jump to next window displaying buffer number #
up: switch to window above current one
down: switch to window below current one
left: switch to window on the left
right: switch to window on the right
splith: split current window horizontally
splitv: split current window vertically
resize: resize window size, new size is pourcentage of parent window
merge: merge window with another (all = keep only one window)

For splith and splitv, pct is a pourcentage which represents size of new window, computed with current window as size reference. For example 25 means create a new window with size = current_size / 4

Key functions

Function     Description
return     terminate line
tab     complete word
tab_previous     find previous completion for word
backspace     delete previous char
delete     delete next char
delete_end_line     delete until end of line
delete_beginning_line     delete until beginning of line
delete_line     delete entire line
delete_previous_word     delete previous word
delete_next_word     delete next word
clipboard_paste     paste current clipboard content
transpose_chars     transpose chars
home     go to beginning of line
end     go to end of line
left     move one char left
previous_word     move to previous word
right     move one char right
next_word     move to next word
up     call previous command in history
up_global     call previous command in global history
down     call next command in history
down_global     call next command in global history
page_up     scroll one page up
page_down     scroll one page down
scroll_up     scroll a few lines up
scroll_down     scroll a few lines down
scroll_top     scroll to top of buffer
scroll_bottom     scroll to bottom of buffer
scroll_topic_left     scroll left topic
scroll_topic_right     scroll right topic
nick_beginning     display beginning of nicklist
nick_end     display end of nicklist
nick_page_up     scroll nicklist one page up
nick_page_down     scroll nicklist one page down
jump_smart     jump to buffer with activity
jump_dcc     jump to DCC buffer
jump_raw_data     jump to raw IRC data buffer
jump_last_buffer     jump to last buffer
jump_previous_buffer     jump to previous buffer
jump_server     jump to server buffer
jump_next_server     jump to next server
switch_server     switch active server on servers buffer
scroll_previous_highlight     scroll to previous highlight in buffer
scroll_next_highlight     scroll to next highlight in buffer
scroll_unread     scroll to first unread line in buffer
set_unread     set unread marker on all buffers
hotlist_clear     clear hotlist
infobar_clear     clear infobar
refresh     refresh screen
grab_key     grab a key
insert     insert a string in command line
search_text     search text in buffer history

IRC commands

admin [target]

find information about the administrator of the server

target: server

ame message

send a CTCP action to all channels of all connected servers

message: message to send

amsg text

send message to all channels of all connected servers

text: text to send

away [-all] [message]

toggle away status

-all: toggle away status on all connected servers
message: message for away (if no message is given, away status is removed)

ban [channel] [nickname [nickname ...]]

bans nicks or hosts

channel: channel for ban
nickname: user or host to ban

ctcp receiver type [arguments]

send a CTCP message (Client-To-Client Protocol)

receiver: nick or channel to send CTCP to
type: CTCP type (examples: “version”, “ping”, ..)
arguments: arguments for CTCP

cycle [channel[,channel]] [part_message]

leave and rejoin a channel

channel: channel name for cycle
part_message: part message (displayed to other users)

dehalfop [nickname [nickname]]

removes half channel operator status from nickname(s)

deop [nickname [nickname]]

removes channel operator status from nickname(s)

devoice [nickname [nickname]]

removes voice from nickname(s)

die

shutdown the server

halfop [nickname [nickname]]

gives half channel operator status to nickname(s)

info [target]

get information describing the server

target: server name

invite nickname channel

invite a nick on a channel

nickname: nick to invite
channel: channel to invite

ison nickname [nickname ...]

check if a nickname is currently on IRC

nickname: nickname

join channel[,channel] [key[,key]]

join a channel

channel: channel name to join
key: key to join the channel

kick [channel] nickname [comment]

forcibly remove a user from a channel

channel: channel where user is
nickname: nickname to kick
comment: comment for kick

kickban [channel] nickname [comment]

kicks and bans a nick from a channel

channel: channel where user is
nickname: nickname to kick and ban
comment: comment for kick

kill nickname comment

close client-server connection

nickname: nickname
comment: comment for kill

links [[server] server_mask]

list all servernames which are known by the server answering the query

server: this server should answer the query
server_mask: list of servers must match this mask

list [channel[,channel] [server]]

list channels and their topic

channel: channel to list (a regexp is allowed)
server: server name

lusers [mask [target]]

get statistics about the size of the IRC network

mask: servers matching the mask only
target: server for forwarding request

me message

send a CTCP action to the current channel

message: message to send

mode { channel {[+|-]|o|p|s|i|t|n|b|v} [limit] [user] [ban mask] } | { nickname {[+|-]|i|w|s|o} }

change channel or user mode

channel modes:
channel: channel name to modify
o: give/take channel operator privileges
p: private channel flag
s: secret channel flag
i: invite-only channel flag
t: topic settable by channel operator only flag
n: no messages to channel from clients on the outside
m: moderated channel
l: set the user limit to channel
b: set a ban mask to keep users out
e: set exception mask
v: give/take the ability to speak on a moderated channel
k: set a channel key (password)
user modes:
nickname: nickname to modify
i: mark a user as invisible
s: mark a user for receive server notices
w: user receives wallops
o: operator flag

motd [target]

get the “Message Of The Day”

target: server name

msg receiver[,receiver] text

send message to a nick or channel

receiver: nick or channel (may be mask, ‘*’ = current channel)
text: text to send

names [channel[,channel]]

list nicknames on channels

channel: channel name

nick [-all] nickname

change current nickname

-all: set new nickname for all connected servers
nickname: new nickname

notice nickname text

send notice message to user

nickname: user to send notice to
text: text to send

op nickname [nickname]

gives channel operator status to nickname(s)

oper user password

get operator privileges

user/password: used to get privileges on current IRC server

part [channel[,channel]] [part_message]

leave a channel

channel: channel name to leave
part_message: part message (displayed to other users)

ping server1 [server2]

ping server

server1: server to ping
server2: forward ping to this server

pong daemon [daemon2]

answer to a ping message

daemon: daemon who has responded to Ping message
daemon2: forward message to this daemon

query nickname [text]

send a private message to a nick

nickname: nickname for private conversation
text: text to send

quit [quit_message]

close all connections and quit

quit_message: quit message (displayed to other users)

quote data

send raw data to server without parsing

data: raw data to send

rehash

tell the server to reload its config file

restart

tell the server to restart itself

service nickname reserved distribution type reserved info

register a new service

distribution: visibility of service
type: reserved for future usage

servlist [mask [type]]

list services currently connected to the network

mask: list only services matching this mask
type: list only services of this type

squery service text

deliver a message to a service

service: name of service
text: text to send

squit server comment

disconnect server links

server: server name
comment: comment for quit

stats [query [server]]

query statistics about server

query: c/h/i/k/l/m/o/y/u (see RFC1459)
server: server name

summon user [target [channel]]

give users who are on a host running an IRC server a message asking them to please join IRC

user: username
target: server name
channel: channel name

time [target]

query local time from server

target: query time from specified server

topic [channel] [topic]

get/set channel topic

channel: channel name
topic: new topic for channel (if topic is “-delete” then topic is deleted)

trace [target]

find the route to specific server

target: server

unban [channel] nickname [nickname ...]

unbans nicks or hosts

channel: channel for unban
nickname: user or host to unban

userhost nickname [nickname ...]

return a list of information about nicknames

nickname: nickname

users [target]

list of users logged into the server

target: server

version [server | nickname]

gives the version info of nick or server (current or specified)

server: server name
nickname: nickname

voice [nickname [nickname]]

gives voice to nickname(s)

wallops text

send a message to all currently connected users who have set the ‘w’ user mode for themselves

text to send

who [mask ["o"]]

generate a query which returns a list of information

mask: only information which match this mask
o: only operators are returned according to the mask supplied

whois [server] nickname[,nickname]

query information about user(s)

server: server name
nickname: nickname (may be a mask)

whowas nickname [,nickname [,nickname ...]] [count [target]]

ask for information about a nickname which no longer exists

nickname: nickname to search
count: number of replies to return (full search if negative number)
target: reply should match this mask

Configuration file

List of options for config file:
Option     Type     Values     Default     Description
look_save_on_exit     boolean     ‘on’ or ‘off’     ‘on’     Save config file on exit
look_set_title     boolean     ‘on’ or ‘off’     ‘on’     Set title for window (terminal for Curses GUI) with name and version
look_startup_logo     boolean     ‘on’ or ‘off’     ‘on’     Display WeeChat logo at startup
look_startup_version     boolean     ‘on’ or ‘off’     ‘on’     Display WeeChat version at startup
look_weechat_slogan     string     any string     ‘the geekest IRC client!’     WeeChat slogan (if empty, slogan is not used)
look_one_server_buffer     boolean     ‘on’ or ‘off’     ‘off’     Use same buffer for all servers
look_open_near_server     boolean     ‘on’ or ‘off’     ‘off’     Open new channels/privates near server
look_scroll_amount     integer     between 1 and 2147483647     3     How many lines to scroll by with scroll_up and scroll_down
look_buffer_timestamp     string     any string     ‘[%H:%M:%S]‘     Timestamp for buffers
look_color_nicks_number     integer     between 1 and 10     10     Number of colors to use for nicks colors
look_color_actions     boolean     ‘on’ or ‘off’     ‘on’     Display actions with different colors
look_nicklist     boolean     ‘on’ or ‘off’     ‘on’     Display nicklist window (for channel windows)
look_nicklist_position     string     ‘left’, ‘right’, ‘top’, ‘bottom’     ‘right’     Nicklist position (top, left, right (default), bottom)
look_nicklist_min_size     integer     between 0 and 100     0     Min size for nicklist (width or height, depending on look_nicklist_position (0 = no min size))
look_nicklist_max_size     integer     between 0 and 100     0     Max size for nicklist (width or height, depending on look_nicklist_position (0 = no max size; if min = max and > 0, then size is fixed))
look_nicklist_separator     boolean     ‘on’ or ‘off’     ‘on’     Separator between chat and nicklist
look_no_nickname     string     any string     ‘-cmd-’     Text to display instead of nick when not connected
look_nickmode     boolean     ‘on’ or ‘off’     ‘on’     Display nick mode ((half)op/voice) before each nick
look_nickmode_empty     boolean     ‘on’ or ‘off’     ‘off’     Display space if nick mode is not (half)op/voice
look_nick_prefix     string     any string     ”     Text to display before nick in chat window
look_nick_suffix     string     any string     ‘ |’     Text to display after nick in chat window
look_align_nick     string     ‘none’, ‘left’, ‘right’     ‘right’     Nick alignment (fixed size for nicks in chat window (none, left, right))
look_align_other     boolean     ‘on’ or ‘off’     ‘on’     Alignment for other messages (not beginning with a nick)
look_align_size     integer     between 8 and 64     14     Size for aligning nick and other messages
look_align_size_max     integer     between 8 and 64     20     Max size for aligning nick and other messages (should be >= to look_align_size)
look_align_text_offset     integer     between -1 and 64     -1     Offset for aligning lines of messages (except first lines), default is -1 (align after nick), a null or positive value is offset after beginning of line
look_nick_completor     string     any string     ‘:’     The string inserted after nick completion
look_nick_completion_ignore     string     any string     ‘[]-^’     Chars ignored for nick completion
look_nick_completion_smart     boolean     ‘on’ or ‘off’     ‘on’     Smart completion for nicks (completes with last speakers first)
look_nick_complete_first     boolean     ‘on’ or ‘off’     ‘off’     Complete only with first nick found
look_infobar     boolean     ‘on’ or ‘off’     ‘on’     Enable info bar
look_infobar_timestamp     string     any string     ‘%B, %A %d %Y’     Timestamp for time in infobar
look_infobar_seconds     boolean     ‘on’ or ‘off’     ‘on’     Display seconds in infobar time
look_infobar_delay_highlight     integer     between 0 and 2147483647     7     Delay (in seconds) for highlight messages in infobar (0 = disable highlight notifications in infobar)
look_hotlist_names_count     integer     between 0 and 32     3     Max number of names in hotlist (0 = no name displayed, only buffer numbers)
look_hotlist_names_level     integer     between 1 and 15     12     Level for displaying names in hotlist (combination of: 1=join/part, 2=message, 4=private, 8=highlight, for example: 12=private+highlight)
look_hotlist_names_length     integer     between 0 and 32     0     Max length of names in hotlist (0 = no limit)
look_hotlist_sort     string     ‘group_time_asc’, ‘group_time_desc’, ‘group_number_asc’, ‘group_number_desc’, ‘number_asc’, ‘number_desc’     ‘group_time_asc’     Hotlist sort type (group_time_asc (default), group_time_desc, group_number_asc, group_number_desc, number_asc, number_desc)
look_day_change     boolean     ‘on’ or ‘off’     ‘on’     Display special message when day changes
look_day_change_timestamp     string     any string     ‘%a, %d %b %Y’     Timestamp for date displayed when day changed
look_read_marker     char     any char     ‘ ‘     Use a marker on servers/channels to show first unread line
look_input_format     string     any string     ‘[%n(%m)] ‘     Format for input prompt (‘%c’ is replaced by channel or server, ‘%n’ by nick and ‘%m’ by nick modes)
look_paste_max_lines     integer     between 0 and 2147483647     3     Max number of lines for paste without asking user (0 = disable this feature)
col_real_white     boolean     ‘on’ or ‘off’     ‘off’     If set, uses real white color, disabled by default for terms with white background (if you never use white background, you should turn on this option to see real white instead of default term foreground color)
col_separator     color     Curses or Gtk color     ‘blue’     Color for window separators (when splited)
col_title     color     Curses or Gtk color     ‘default’     Color for title bar
col_title_more     color     Curses or Gtk color     ‘lightmagenta’     Color for ‘+’ when scrolling topic
col_title_bg     color     Curses or Gtk color     ‘blue’     Background for title bar
col_chat     color     Curses or Gtk color     ‘default’     Color for chat text
col_chat_time     color     Curses or Gtk color     ‘default’     Color for time in chat window
col_chat_time_sep     color     Curses or Gtk color     ‘brown’     Color for time separator (chat window)
col_chat_prefix1     color     Curses or Gtk color     ‘lightcyan’     Color for 1st and 3rd char of prefix
col_chat_prefix2     color     Curses or Gtk color     ‘white’     Color for middle char of prefix
col_chat_server     color     Curses or Gtk color     ‘brown’     Color for server name
col_chat_join     color     Curses or Gtk color     ‘lightgreen’     Color for join arrow (prefix)
col_chat_part     color     Curses or Gtk color     ‘lightred’     Color for part/quit arrow (prefix)
col_chat_nick     color     Curses or Gtk color     ‘lightcyan’     Color for nicks in actions (chat window)
col_chat_host     color     Curses or Gtk color     ‘cyan’     Color for hostnames (chat window)
col_chat_channel     color     Curses or Gtk color     ‘white’     Color for channel names in actions (chat window)
col_chat_dark     color     Curses or Gtk color     ‘green’     Color for dark separators (chat window)
col_chat_highlight     color     Curses or Gtk color     ‘yellow’     Color for highlighted nick (chat window)
col_chat_bg     color     Curses or Gtk color     ‘default’     Background for chat window
col_chat_read_marker     color     Curses or Gtk color     ‘yellow’     Color for unread data marker
col_chat_read_marker_bg     color     Curses or Gtk color     ‘magenta’     Background for unread data marker
col_status     color     Curses or Gtk color     ‘default’     Color for status bar
col_status_delimiters     color     Curses or Gtk color     ‘cyan’     Color for status bar delimiters
col_status_channel     color     Curses or Gtk color     ‘white’     Color for current channel in status bar
col_status_data_msg     color     Curses or Gtk color     ‘yellow’     Color for window with new messages (status bar)
col_status_private     color     Curses or Gtk color     ‘lightmagenta’     Color for window with private message (status bar)
col_status_highlight     color     Curses or Gtk color     ‘lightred’     Color for window with highlight (status bar)
col_status_data_other     color     Curses or Gtk color     ‘default’     Color for window with new data (not messages) (status bar)
col_status_more     color     Curses or Gtk color     ‘white’     Color for window with new data (status bar)
col_status_bg     color     Curses or Gtk color     ‘blue’     Background for status window
col_infobar     color     Curses or Gtk color     ‘black’     Color for info bar text
col_infobar_delimiters     color     Curses or Gtk color     ‘blue’     Color for infobar delimiters
col_infobar_highlight     color     Curses or Gtk color     ‘white’     Color for info bar highlight notification
col_infobar_bg     color     Curses or Gtk color     ‘cyan’     Background for info bar window
col_input     color     Curses or Gtk color     ‘default’     Color for input text
col_input_server     color     Curses or Gtk color     ‘brown’     Color for input text (server name)
col_input_channel     color     Curses or Gtk color     ‘white’     Color for input text (channel name)
col_input_nick     color     Curses or Gtk color     ‘lightcyan’     Color for input text (nick name)
col_input_delimiters     color     Curses or Gtk color     ‘cyan’     Color for input text (delimiters)
col_input_text_not_found     color     Curses or Gtk color     ‘red’     Color for text not found
col_input_actions     color     Curses or Gtk color     ‘lightgreen’     Color for actions in input window
col_input_bg     color     Curses or Gtk color     ‘default’     Background for input window
col_nick     color     Curses or Gtk color     ‘default’     Color for nicknames
col_nick_away     color     Curses or Gtk color     ‘cyan’     Color for away nicknames
col_nick_chanowner     color     Curses or Gtk color     ‘lightgreen’     Color for chan owner symbol (specific to unrealircd)
col_nick_chanadmin     color     Curses or Gtk color     ‘lightgreen’     Color for chan admin symbol (specific to unrealircd)
col_nick_op     color     Curses or Gtk color     ‘lightgreen’     Color for operator symbol
col_nick_halfop     color     Curses or Gtk color     ‘lightmagenta’     Color for half-operator symbol
col_nick_voice     color     Curses or Gtk color     ‘yellow’     Color for voice symbol
col_nick_user     color     Curses or Gtk color     ‘blue’     Color for user symbol
col_nick_more     color     Curses or Gtk color     ‘lightmagenta’     Color for ‘+’ when scrolling nicks
col_nick_sep     color     Curses or Gtk color     ‘blue’     Color for nick separator
col_nick_self     color     Curses or Gtk color     ‘white’     Color for local nick
col_nick_color1     color     Curses or Gtk color     ‘cyan’     Color for nick
col_nick_color2     color     Curses or Gtk color     ‘magenta’     Color for nick
col_nick_color3     color     Curses or Gtk color     ‘green’     Color for nick
col_nick_color4     color     Curses or Gtk color     ‘brown’     Color for nick
col_nick_color5     color     Curses or Gtk color     ‘lightblue’     Color for nick
col_nick_color6     color     Curses or Gtk color     ‘default’     Color for nick
col_nick_color7     color     Curses or Gtk color     ‘lightcyan’     Color for nick
col_nick_color8     color     Curses or Gtk color     ‘lightmagenta’     Color for nick
col_nick_color9     color     Curses or Gtk color     ‘lightgreen’     Color for nick
col_nick_color10     color     Curses or Gtk color     ‘blue’     Color for nick
col_nick_private     color     Curses or Gtk color     ‘default’     Color for other nick in private window
col_nick_bg     color     Curses or Gtk color     ‘default’     Background for nicknames
col_chat_dcc_selected     color     Curses or Gtk color     ‘white’     Color for selected DCC (chat window)
col_dcc_waiting     color     Curses or Gtk color     ‘lightcyan’     Color for “waiting” dcc status
col_dcc_connecting     color     Curses or Gtk color     ‘yellow’     Color for “connecting” dcc status
col_dcc_active     color     Curses or Gtk color     ‘lightblue’     Color for “active” dcc status
col_dcc_done     color     Curses or Gtk color     ‘lightgreen’     Color for “done” dcc status
col_dcc_failed     color     Curses or Gtk color     ‘lightred’     Color for “failed” dcc status
col_dcc_aborted     color     Curses or Gtk color     ‘lightred’     Color for “aborted” dcc status
history_max_lines     integer     between 0 and 2147483647     4096     Maximum number of lines in history for one server/channel/private window (0 = unlimited)
history_max_commands     integer     between 0 and 2147483647     100     Maximum number of user commands in history (0 = unlimited)
history_display_default     integer     between 0 and 2147483647     5     Maximum number of commands to display by default in history listing (0 = unlimited)
log_auto_server     boolean     ‘on’ or ‘off’     ‘off’     Automatically log server messages
log_auto_channel     boolean     ‘on’ or ‘off’     ‘off’     Automatically log channel chats
log_auto_private     boolean     ‘on’ or ‘off’     ‘off’     Automatically log private chats
log_plugin_msg     boolean     ‘on’ or ‘off’     ‘off’     Log messages from plugins (scripts)
log_path     string     any string     ‘%h/logs/’     Path for WeeChat log files (‘%h’ will be replaced by WeeChat home, ~/.weechat by default)
log_timestamp     string     any string     ‘%Y %b %d %H:%M:%S’     Timestamp for log (see man strftime for date/time specifiers)
log_hide_nickserv_pwd     boolean     ‘on’ or ‘off’     ‘on’     Hide password displayed by nickserv
irc_display_away     string     ‘off’, ‘local’, ‘channel’     ‘off’     Display message when (un)marking as away
irc_show_away_once     boolean     ‘on’ or ‘off’     ‘on’     Show remote away message only once in private
irc_default_msg_part     string     any string     ‘WeeChat %v’     Default part message (leaving channel) (‘%v’ will be replaced by WeeChat version in string)
irc_default_msg_quit     string     any string     ‘WeeChat %v’     Default quit message (‘%v’ will be replaced by WeeChat version in string)
irc_notice_as_pv     boolean     ‘on’ or ‘off’     ‘off’     Display notices as private messages
irc_away_check     integer     between 0 and 2147483647     0     Interval between two checks for away (in minutes, 0 = never check)
irc_away_check_max_nicks     integer     between 0 and 2147483647     0     Do not check away nicks on channels with high number of nicks (0 = unlimited)
irc_lag_check     integer     between 30 and 2147483647     60     Interval between two checks for lag (in seconds)
irc_lag_min_show     integer     between 0 and 2147483647     1     Minimum lag to show (in seconds)
irc_lag_disconnect     integer     between 0 and 2147483647     5     Disconnect after important lag (in minutes, 0 = never disconnect)
irc_anti_flood     integer     between 0 and 5     2     Anti-flood: # seconds between two user messages (0 = no anti-flood)
irc_fifo_pipe     boolean     ‘on’ or ‘off’     ‘off’     Create a FIFO pipe for remote control
irc_highlight     string     any string     ”     Comma separated list of words to highlight (case insensitive comparison, words may begin or end with “*” for partial match)
irc_colors_receive     boolean     ‘on’ or ‘off’     ‘on’     When off, colors codes are ignored in incoming messages
irc_colors_send     boolean     ‘on’ or ‘off’     ‘on’     Allow user to send colors with special codes (^Cb=bold, ^Ccxx=color, ^Ccxx,yy=color+background, ^Cu=underline, ^Cr=reverse)
irc_send_unknown_commands     boolean     ‘on’ or ‘off’     ‘off’     Send unknown commands to IRC server
dcc_auto_accept_files     boolean     ‘on’ or ‘off’     ‘off’     Automatically accept incoming dcc files
dcc_auto_accept_chats     boolean     ‘on’ or ‘off’     ‘off’     Automatically accept dcc chats (use carefully!)
dcc_timeout     integer     between 5 and 2147483647     300     Timeout for dcc request (in seconds)
dcc_blocksize     integer     between 1024 and 102400     65536     Block size for dcc packets in bytes (default: 65536)
dcc_fast_send     boolean     ‘on’ or ‘off’     ‘on’     Does not wait for ACK when sending file
dcc_port_range     string     any string     ”     Restricts outgoing dcc to use only ports in the given range (useful for NAT) (syntax: a single port, ie. 5000 or a port range, ie. 5000-5015, empty value means any port)
dcc_own_ip     string     any string     ”     IP or DNS address used for outgoing dcc (if empty, local interface IP is used)
dcc_download_path     string     any string     ‘%h/dcc’     Path for writing incoming files with dcc (default: user home)
dcc_upload_path     string     any string     ‘~’     Path for reading files when sending thru dcc (when no path is specified)
dcc_convert_spaces     boolean     ‘on’ or ‘off’     ‘on’     Convert spaces to underscores when sending files
dcc_auto_rename     boolean     ‘on’ or ‘off’     ‘on’     Rename incoming files if already exists (add ‘.1′, ‘.2′, …)
dcc_auto_resume     boolean     ‘on’ or ‘off’     ‘on’     Automatically resume dcc transfer if connection with remote host is loosed
proxy_use     boolean     ‘on’ or ‘off’     ‘off’     Use a proxy server to connect to irc server
proxy_type     string     ‘http’, ‘socks4′, ‘socks5′     ‘http’     Proxy type (http (default), socks4, socks5)
proxy_ipv6     boolean     ‘on’ or ‘off’     ‘off’     Connect to proxy in ipv6
proxy_address     string     any string     ”     Proxy server address (IP or hostname)
proxy_port     integer     between 0 and 65535     3128     Port for connecting to proxy server
proxy_username     string     any string     ”     Username for proxy server
proxy_password     string     any string     ”     Password for proxy server
plugins_path     string     any string     ‘%h/plugins’     Path for searching plugins (‘%h’ will be replaced by WeeChat home, ~/.weechat by default)
plugins_autoload     string     any string     ‘*’     Comma separated list of plugins to load automatically at startup, “*” means all plugins found (names may be partial, for example “perl” is ok for “libperl.so”)
plugins_extension     string     any string     ‘.so’     Standard plugins extension in filename, used for autoload (if empty, then all files are loaded when autoload is “*”)
server_name     string     any string     ”     Name associated to IRC server (for display only)
server_autoconnect     boolean     ‘on’ or ‘off’     ‘on’     Automatically connect to server when WeeChat is starting
server_autoreconnect     boolean     ‘on’ or ‘off’     ‘on’     Automatically reconnect to server when disconnected
server_autoreconnect_delay     integer     between 0 and 65535     30     Delay (in seconds) before trying again to reconnect to server
server_address     string     any string     ”     IP address or hostname of IRC server
server_port     integer     between 0 and 65535     6667     Port for connecting to server
server_ipv6     boolean     ‘on’ or ‘off’     ‘off’     Use IPv6 protocol for server communication
server_ssl     boolean     ‘on’ or ‘off’     ‘off’     Use SSL for server communication
server_password     string     any string     ”     Password for IRC server
server_nick1     string     any string     ”     Nickname to use on IRC server
server_nick2     string     any string     ”     Alternate nickname to use on IRC server (if nickname is already used)
server_nick3     string     any string     ”     2nd alternate nickname to use on IRC server (if alternate nickname is already used)
server_username     string     any string     ”     User name to use on IRC server
server_realname     string     any string     ”     Real name to use on IRC server
server_hostname     string     any string     ”     Custom hostname/IP for server (optional, if empty local hostname is used)
server_command     string     any string     ”     Command(s) to run when connected to server (many commands should be separated by ‘;’, use ‘;’ for a semicolon, special variables $nick, $channel and $server are replaced by their value)
server_command_delay     integer     between 0 and 3600     0     Delay (in seconds) after command was executed (example: give some time for authentication)
server_autojoin     string     any string     ”     Comma separated list of channels to join when connected to server (example: “#chan1,#chan2,#chan3 key1,key2″)
server_autorejoin     boolean     ‘on’ or ‘off’     ‘on’     Automatically rejoin channels when kicked
server_notify_levels     string     any string     ”     Comma separated list of notify levels for channels of this server (format: #channel:1,..), a channel name ‘*’ is reserved for server default notify level

Colors for Curses GUI are:
Keyword     Color
default     default color (transparent for background)
black     black
red     dark red
lightred     light red
green     dark green
lightgreen     light green
brown     brown
yellow     yellow
blue     dark blue
lightblue     light blue
magenta     dark magenta
lightmagenta     light magenta
cyan     dark cyan
lightcyan     light cyan
white     white

FIFO pipe

You can remote control WeeChat, by sending commands or text to a FIFO pipe (you have to enable option “irc_fifo_pipe”, it is disabled by default).

The FIFO pipe is located in “~/.weechat/” and is called “weechat_fifo_xxxxx” (where xxxxx is the process ID (PID) of running WeeChat). So if many WeeChat are running, you have many FIFO pipes, one for each session.

The syntax for the FIFO pipe commands/text is:

server,channel *text or command here

where server and channel are optional, but if channel is here, server should be too.

Some examples:

*

nick change on freenode to “mynick|out” :

$ echo ‘freenode */nick mynick|out’ >~/.weechat/weechat_fifo_12345

*

display text on #weechat channel:

$ echo ‘freenode,#weechat *hello everybody!’ >~/.weechat/weechat_fifo_12345

*

display text on current channel (buffer displayed by WeeChat):

$ echo ‘*hello!’ >~/.weechat/weechat_fifo_12345

Warning: this is dangerous and you should not do that except if you know what you do!
*

send two commands to unload/reload Perl scripts (you have to separate them with “n”):

$ echo -e “freenode */perl unloadnfreenode */perl autoload” >~/.weechat/weechat_fifo_12345

You can write a script to send command to all running WeeChat at same time, for example:

#!/bin/sh
if [ $# -eq 1 ]; then
for fifo in ~/.weechat/weechat_fifo_*
do
echo -e “$1″ >$fifo
done
fi

If the script is called “auto_weechat_command”, you can run it with:

$ ./auto_weechat_command “freenode,#weechat *hello”

Chapter 4. Plugins

Table of Contents

Plugins in WeeChat
Write a plugin

API functions
Compile plugin
Load plugin into WeeChat
Plugin example

Charset plugin

Settings
FAQ

Scripts plugins

Load / unload scripts
Syntax by language
WeeChat / scripts API

This chapter describes WeeChat plugins interface (API) and the default scripts plugins (Perl, Python, Ruby, Lua), provided with WeeChat.
Plugins in WeeChat

A plugin is a C program which can call WeeChat functions defined in an interface.

This C program does not need WeeChat sources to compile and can be dynamically loaded into WeeChat with command /plugin.

The plugin has to be a dynamic library, for dynamic loading by operating system. Under GNU/Linux, the file has “.so” extension, “.dll” under Windows.
Write a plugin

API functions
Compile plugin
Load plugin into WeeChat
Plugin example

The plugin has to include “weechat-plugin.h” file (available in WeeChat source code). This file defines structures and types used to communicate with WeeChat.

The plugin must have some variables and functions (mandatory, without them the plugin can’t load):
Variable     Description
char plugin_name[]     plugin name
char plugin_version[]     plugin version
char plugin_description[]     short description of plugin

Function     Description
int weechat_plugin_init (t_weechat_plugin *plugin)     function called when plugin is loaded, must return PLUGIN_RC_OK if successful, PLUGIN_RC_KO if error (if error, plugin will NOT be loaded)
void weechat_plugin_end (t_weechat_plugin *plugin)     function called when plugin is unloaded

API functions

set_charset
iconv_to_internal
iconv_from_internal
ascii_strcasecmp
ascii_strncasecmp
explode_string
free_exploded_string
mkdir_home
exec_on_files
print
print_server
print_infobar
infobar_remove
log
msg_handler_add
cmd_handler_add
timer_handler_add
keyboard_handler_add
event_handler_add
handler_remove
handler_remove_all
modifier_add
modifier_remove
modifier_remove_all
exec_command
get_info
get_dcc_info
free_dcc_info
get_server_info
free_server_info
get_channel_info
free_channel_info
get_nick_info
free_nick_info
get_config
set_config
get_plugin_config
set_plugin_config
get_irc_color
input_color
get_window_info
free_window_info
get_buffer_info
free_buffer_info
get_buffer_data
free_buffer_data

set_charset

Prototype: void set_charset (t_weechat_plugin *plugin, char *charset)

Set new plugin charset.

Arguments:

*

plugin: pointer to plugin structure
*

charset: new charset to use

Example:

plugin->set_charset (plugin, “ISO-8859-1″);

iconv_to_internal

Prototype: void iconv_to_internal (t_weechat_plugin *plugin, char *charset, char *string)

Convert string to WeeChat internal charset (UTF-8).

Arguments:

*

plugin: pointer to plugin structure
*

charset: charset to convert
*

string: string to convert

Return value: converted string.

Note: result has to be free by a call to “free” after use.

Example:

char *str = plugin->iconv_to_internal (plugin, “ISO-8859-1″, “iso string: é à”);

iconv_from_internal

Prototype: void iconv_from_internal (t_weechat_plugin *plugin, char *charset, char *string)

Convert string from internal WeeChat charset (UTF-8) to another.

Arguments:

*

plugin: pointer to plugin structure
*

charset: target charset
*

string: string to convert

Return value: converted string.

Note: result has to be free by a call to “free” after use.

Example:

char *str = plugin->iconv_from_internal (plugin, “ISO-8859-1″, “utf-8 string: é à”);

ascii_strcasecmp

Prototype: int ascii_strcasecmp (t_weechat_plugin *plugin, char *string1, char *string2)

Locale and case independent string comparison.

Arguments:

*

plugin: pointer to plugin structure
*

string1: first string for comparison
*

string2: second string for comparison

Return value: difference between two strings: negative if string1 string2

Example:

if (plugin->ascii_strcasecmp (plugin, “abc”, “def”) != 0) …

ascii_strncasecmp

Prototype: int ascii_strncasecmp (t_weechat_plugin *plugin, char *string1, char *string2, int max)

Locale and case independent string comparison, for “max” chars.

Arguments:

*

plugin: pointer to plugin struct
*

string1: first string for comparison
*

string2: second string for comparison
*

max: max number of chars for comparison

Return value: difference between two strings: negative if string1 string2

Example:

if (plugin->ascii_strncasecmp (plugin, “abc”, “def”, 2) != 0) …

explode_string

Prototype: char **explode_string (t_weechat_plugin *plugin, char *string, char *separators, int num_items_max, int *num_items)

Explode a string according to one or more delimiter(s).

Arguments:

*

plugin: pointer to plugin struct
*

string: string to explode
*

separators: delimiters used for explosion
*

num_items_max: maximum number of items created (0 = no limit)
*

num_items: pointer to int which will contain number of items created

Return value: array of strings, NULL if problem.

Note: result has to be free by a call to “free_exloded_string” after use.

Example:

char **argv;
int argc;
argv = plugin->explode_string (plugin, string, ” “, 0, &argc);

if (argv != NULL)
plugin->free_exploded_string (plugin, argv);

free_exploded_string

Prototype: char **free_exploded_string (t_weechat_plugin *plugin, char **string)

Free memory used by a string explosion.

Arguments:

*

plugin: pointer to plugin structure
*

string: string exploded by “explode_string” function

Return value: none.

Example:

char *argv;
int argc;
argv = plugin->explode_string (plugin, string, ” “, 0, &argc);

if (argv != NULL)
plugin->free_exploded_string (plugin, argv);

mkdir_home

Prototype: int mkdir_home (t_weechat_plugin *plugin, char *directory)

Create a directory in WeeChat home.

Arguments:

*

plugin: pointer to plugin structure
*

directory: directory to create

Return value: 1 if directory was successfully created, 0 if an error occurred.

Example:

if (!plugin->mkdir_home (plugin, “temp”))
plugin->print_server(plugin, “Failed to create ‘temp’ directory in WeeChat home.”);

exec_on_files

Prototype: void exec_on_files (t_weechat_plugin *plugin, char *directory, int (*callback)(t_weechat_plugin *, char *))

Execute a function on all files of a directory.

Arguments:

*

plugin: pointer to plugin structure
*

directory: directory for searching files
*

callback: function called for each file found

Return value: none.

Example:

int callback (t_weechat_plugin *plugin, char *file)
{
plugin->print_server (plugin, “file: %s”, file);
return 1;
}

plugin->exec_on_files (plugin, “/tmp”, &callback);

print

Prototype: void print (t_weechat_plugin *plugin, char *server, char *channel, char *message, …)

Display a message on a WeeChat buffer, identified by server and channel (both may be NULL for current buffer).

Arguments:

*

plugin: pointer to plugin structure
*

server: internal name of server to find buffer for message display (may be NULL)
*

channel: name of channel to find buffer for message display (may be NULL)
*

message: message

To display colored text, there are following codes:
Code     Description
0×02     bold text
0×03 + “xx”     text color “xx” (see the section called “get_irc_color” for colors)
0×03 + “xx,yy”     text color “xx” and background “yy” (see the section called “get_irc_color” for colors)
0x0F     disable color and attributes
0×12     reverse video (revert text color with background)
0x1F     underlined text

Note: the same code (without number for 0×03) may be used to stop the attribute.

Return value: none.

Examples:

plugin->print (plugin, NULL, NULL, “hello”);
plugin->print (plugin, NULL, “#weechat”, “hello”);
plugin->print (plugin, “freenode”, “#weechat”, “hello”);
plugin->print (plugin, NULL, NULL,
“test: x02 bold x0Fx03%02d blue x03%02d green”,
plugin->get_irc_color (plugin, “blue”),
plugin->get_irc_color (plugin, “green”));

print_server

Prototype: void print_server (t_weechat_plugin *plugin, char *message, …)

Display a message on current server buffer.

Arguments:

*

plugin: pointer to plugin structure
*

message: message

To display colored text, see the section called “print”.

Return value: none.

Example:

plugin->print_server (plugin, “hello”);

print_infobar

Prototype: void print_infobar (t_weechat_plugin *plugin, int time, char *message, …)

Display a message in infobar for a specified time.

Arguments:

*

plugin: pointer to plugin structure
*

time: time (in seconds) for displaying message (0 = never erased)

Return value: none.

Example:

plugin->print_infobar (plugin, 5, “hello”);

infobar_remove

Prototype: void infobar_remove (t_weechat_plugin *plugin, int count)

Remove one or more messages in infobar stack.

Arguments:

*

plugin: pointer to plugin structure
*

count: number of messages to remove (if argument is infobar_remove (1);

log

Prototype: void log (t_weechat_plugin *plugin, char *server, char *channel, char *message, …)

Write a message in log file for a server or a channel.

Arguments:

*

plugin: pointer to plugin structure
*

server: internal name of server to find buffer for log (may be NULL)
*

channel: name of channel to find buffer for log (may be NULL)
*

message: message

Return value: none.

Example:

plugin->log (plugin, “freenode”, “#weechat”, “test”);

msg_handler_add

Prototype: t_plugin_handler *msg_handler_add (t_weechat_plugin *plugin, char *message, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)

Add an IRC message handler, called when an IRC message is received.

Arguments:

*

plugin: pointer to plugin structure
*

message: name of IRC message (“*” for all messages). To know list of IRC messages, please consult RFCs 1459 and 2812. Moreover you can use a special name, prefixed by “weechat_” to catch special events, as written in table below:
Name     Description
weechat_pv     private message received
weechat_highlight     message with highlight (on a channel or pv)
weechat_ctcp     CTCP message received (VERSION, PING, ..)
weechat_dcc     DCC message received (chat or file)

*

function: function called when message is received

It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

Argument argc is set to 3, following values are set in argv array:
o

argv[0] = server name
o

argv[1] = IRC message
o

argv[2] = command arguments

*

handler_args: arguments given to function when called
*

handler_pointer: pointer given to function when called

Return value: pointer to new message handler.

Note: function called when message is received has to return one of following values:

*

PLUGIN_RC_KO: function failed
*

PLUGIN_RC_OK: function successfully completed
*

PLUGIN_RC_OK_IGNORE_WEECHAT: message will not be sent to WeeChat
*

PLUGIN_RC_OK_IGNORE_PLUGINS: message will not be sent to other plugins
*

PLUGIN_RC_OK_IGNORE_ALL: message will not be sent to WeeChat neither other plugins
*

PLUGIN_RC_OK_WITH_HIGHLIGHT: function successfully completed and make “highlight” on received message

Example:

int msg_kick (t_weechat_plugin *plugin, int argc, char **argv,
char *handler_args, void *handler_pointer)
{
plugin->print (plugin, argv[0], NULL, “KICK received”);
return PLUGIN_RC_OK;
}

t_plugin_handler *msg_handler;
msg_handler = plugin->msg_handler_add (plugin, “KICK”,
&msg_kick, NULL, NULL);

cmd_handler_add

Prototype: t_plugin_handler *cmd_handler_add (t_weechat_plugin *plugin, char *command, char *description, char *arguments, char *arguments_description, char *completion_template, t_plugin_handler_func *fonction, char *handler_args, void *handler_pointer)

Add a WeeChat command handler, called when user uses command (for example /command).

Arguments:

*

plugin: pointer to plugin structure
*

command: the new command name, which may be an existing command (be careful, replaced command will not be available until plugin is unloaded)
*

description: short command description (displayed by /help command)
*

arguments: short description of command arguments (displayed by /help command)
*

arguments_description: long description of command arguments (displayed by /help command)
*

completion_template: template for completion, like “abc|%w def|%i” which means “abc” or a WeeChat command for first argument, “def” or IRC command for second. An empty string lets WeeChat complete any argument with a nick from current channel, NULL or “-” disable completion for all command arguments.

Following codes can be used:
Code     Description
%-     no completion for argument
%*     repeat last completion for all following arguments (this code has to be at the end of completion template, preceded by “|”)
%a     alias
%A     alias and commands (WeeChat, IRC and plugins)
%c     current channel
%C     all channels (including queries)
%f     file name
%h     plugins commands
%i     IRC commands (sent)
%I     IRC commands (received)
%k     key functions
%m     nick on current server
%M     nicks on current server (on all open channels)
%n     nicks of current channel
%N     nicks and hostnames of current channel
%o     setup options
%O     plugin options
%p     default “part” message
%q     default “quit” message
%s     current server name
%S     all servers names
%t     topic of current channel
%v     setup option value
%V     plugin option value
%w     WeeChat commands

*

function: function called when command is executed

It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

Argument argc is set to 3, following values are set in argc array:
o

argv[0] = server name
o

argv[1] = command
o

argv[2] = command arguments

*

handler_args: arguments given to function when called
*

handler_pointer: pointer given to function when called

Return value: pointer to new command handler.

Note: function called when command is executed has to return one of following values:

*

PLUGIN_RC_KO: function failed
*

PLUGIN_RC_OK: function successfully completed

Example:

int cmd_test (t_weechat_plugin *plugin, int argc, char **argv,
char *handler_args, void *handler_pointer)
{
plugin->print (plugin, argv[0], NULL,
“test command, nick: %s”,
(argv[2]) ? argv[2] : “none”);
return PLUGIN_RC_OK;
}

t_plugin_handler *cmd_handler;
cmd_handler = plugin->cmd_handler_add (plugin, “test”, “Test command”,
“[nick]“, “nick: nick of channel”,
“%n”, &cmd_test, NULL, NULL);

timer_handler_add

Prototype: t_plugin_handler *timer_handler_add (t_weechat_plugin *plugin, int interval, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)

Add a timer handler which periodically calls a function.

Arguments:

*

plugin: pointer to plugin structure
*

interval: interval (in seconds) between two calls of function.
*

func

Understanding Linux CPU Load – when should you be worried?

You might be familiar with Linux load averages already. Load averages are the three numbers shown with the uptime and top commands – they look like this:
load average: 0.09, 0.05, 0.01

Most people have an inkling of what the load averages mean: the three numbers represent averages over progressively longer periods of time (one, five, and fifteen minute averages), and that lower numbers are better. Higher numbers represent a problem or an overloaded machine. But, what’s the the threshold? What constitutes “good” and “bad” load average values? When should you be concerned over a load average value, and when should you scramble to fix it ASAP?

First, a little background on what the load average values mean. We’ll start out with the simplest case: a machine with one single-core processor.
The traffic analogy

A single-core CPU is like a single lane of traffic. Imagine you are a bridge operator … sometimes your bridge is so busy there are cars lined up to cross. You want to let folks know how traffic is moving on your bridge. A decent metric would be how many cars are waiting at a particular time. If no cars are waiting, incoming drivers know they can drive across right away. If cars are backed up, drivers know they’re in for delays.

So, Bridge Operator, what numbering system are you going to use? How about:

* 0.00 means there’s no traffic on the bridge at all. In fact, between 0.00 and 1.00 means there’s no backup, and an arriving car will just go right on.
* 1.00 means the bridge is exactly at capacity. All is still good, but if traffic gets a little heavier, things are going to slow down.
* over 1.00 means there’s backup. How much? Well, 2.00 means that there are two lanes worth of cars total — one lane’s worth on the bridge, and one lane’s worth waiting. 3.00 means there are three lane’s worth total — one lane’s worth on the bridge, and two lanes’ worth waiting. Etc.

= load of 1.00

= load of 0.50

= load of 1.70

This is basically what CPU load is. “Cars” are processes using a slice of CPU time (“crossing the bridge”) or queued up to use the CPU. Unix refers to this as the run-queue length: the sum of the number of processes that are currently running plus the number that are waiting (queued) to run.

Like the bridge operator, you’d like your cars/processes to never be waiting. So, your CPU load should ideally stay below 1.00. Also like the bridge operator, you are still ok if you get some temporary spikes above 1.00 … but when you’re consistently above 1.00, you need to worry.
So you’re saying the ideal load is 1.00?

Well, not exactly. The problem with a load of 1.00 is that you have no headroom. In practice, many sysadmins will draw a line at 0.70:

*

The “Need to Look into it” Rule of Thumb: 0.70 If your load average is staying above > 0.70, it’s time to investigate before things get worse.
*

The “Fix this now” Rule of Thumb: 1.00. If your load average stays above 1.00, find the problem and fix it now. Otherwise, you’re going to get woken up in the middle of the night, and it’s not going to be fun.
*

The “Arrgh, it’s 3AM WTF?” Rule of Thumb: 5.0. If your load average is above 5.00, you could be in serious trouble, your box is either hanging or slowing way down, and this will (inexplicably) happen in the worst possible time like in the middle of the night or when you’re presenting at a conference. Don’t let it get there.

What about Multi-processors? My load says 3.00, but things are running fine!

Got a quad-processor system? It’s still healthy with a load of 3.00.

On multi-processor system, the load is relative to the number of processor cores available. The “100% utilization” mark is 1.00 on a single-core system, 2.00, on a dual-core, 4.00 on a quad-core, etc.

If we go back to the bridge analogy, the “1.00″ really means “one lane’s worth of traffic”. On a one-lane bridge, that means it’s filled up. On a two-late bridge, a load of 1.00 means its at 50% capacity — only one lane is full, so there’s another whole lane that can be filled.

= load of 2.00 on two-lane road

Same with CPUs: a load of 1.00 is 100% CPU utilization on single-core box. On a dual-core box, a load of 2.00 is 100% CPU utilization.
Multicore vs. multiprocessor

While we’re on the topic, let’s talk about multicore vs. multiprocessor. For performance purposes, is a machine with a single dual-core processor basically equivalent to a machine with two processors with one core each? Yes. Roughly. There are lots of subtleties here concerning amount of cache, frequency of process hand-offs between processors, etc. Despite those finer points, for the purposes of sizing up the CPU load value, the total number of cores is what matters, regardless of how many physical processors those cores are spread across.

Which leads us to a two new Rules of Thumb:

*

The “number of cores = max load” Rule of Thumb: on a multicore system, your load should not exceed the number of cores available.
*

The “cores is cores” Rule of Thumb: How the cores are spread out over CPUs doesn’t matter. Two quad-cores == four dual-cores == eight single-cores. It’s all eight cores for these purposes.

Bringing It Home

Let’s take a look at the load averages output from uptime:
~ $ uptime
23:05 up 14 days, 6:08, 7 users, load averages: 0.65 0.42 0.36

This is on a dual-core CPU, so we’ve got lots of headroom. I won’t even think about it until load gets and stays above 1.7 or so.

Now, what about those three numbers? 0.65 is the average over the last minute, 0.42 is the average over the last five minutes, and 0.36 is the average over the last 15 minutes. Which brings us to the question:

Which average should I be observing? One, five, or 15 minute?

For the numbers we’ve talked about (1.00 = fix it now, etc), you should be looking at the five or 15-minute averages. Frankly, if your box spikes above 1.0 on the one-minute average, you’re still fine. It’s when the 15-minute average goes north of 1.0 and stays there that you need to snap to. (obviously, as we’ve learned, adjust these numbers to the number of processor cores your system has).

So # of cores is important to interpreting load averages … how do I know how many cores my system has?

cat /proc/cpuinfo to get info on each processor in your system. Note: not available on OSX, Google for alternatives. To get just a count, run it through grep and word count: grep ‘model name’ /proc/cpuinfo | wc -l
Monitoring Linux CPU Load with Scout

Scout provides 2 ways to modify the CPU load. Our original server load plugin and Jesse Newland’s Load-Per-Processor plugin both report the CPU load and alert you when the load peaks and/or is trending in the wrong direction:

load alert
More Reading

* Wikipedia – A good, brief explanation of Load Average; it goes a bit deeper into the mathematics
* Linux Journal – very well-written article, goes deeper than either this post or the wikipedia entry.