NAME
- conky - a system monitor for X originally based on the torsmo code, but
- more kickass.
+ conky - A system monitor for X originally based on the torsmo code, but
+ more kickass. It just keeps on given’er. Yeah.
SYNOPSIS
conky [options]
DESCRIPTION
Conky is a system monitor for X originally based on the torsmo code.
- Since it's original conception, Conky has changed a fair bit from it's
+ Since it’s original conception, Conky has changed a fair bit from it’s
predecessor. Conky can display just about anything, either on your
- root desktop or in it's own window. Conky has many built-in objects,
+ root desktop or in it’s own window. Conky has many built-in objects,
as well as the ability to execute programs and scripts, then display
the output from stdout.
Thanks for your interest in Conky.
COMPILING
- First, make sure you have the X development libraries installed, this
- should be a package along the lines of "libx11-dev or xorg-x11-dev".
- Gentoo users, Conky is in Gentoo's Portage. Simply use "emerge conky"
- for installation. There is also usually an up-to-date ebuild within
- Conky's package or in CVS.
+ For users compiling from source, make sure you have the X development
+ libraries installed. This should be a package along the lines of
+ "libx11-dev or xorg-x11-dev".
- To compile and run Conky with all optional components:
+ Gentoo users -- Conky is in Gentoo’s Portage... simply use "emerge app-
+ admin/conky" for installation. There is also usually an up-to-date
+ ebuild within Conky’s package or in CVS.
+
+ Debian,etc. users -- Conky will be in Debian’s repositories soon (by
+ mid-September, hopefully), and then Ubuntu shortly thereafter. Until
+ then, "dpkg -i" the .deb package to install.
+
+ Example to compile and run Conky with all optional components (note
+ that some configure options may differ for your system):
sh autogen.sh # Only required if building from CVS
./configure --prefix=/usr --mandir=/usr/share/man
- --infodir=/usr/share/info --datadir=/usr/ share --sysconfdir=/etc
- --localstatedir=/var/lib --enable-double-buffer --enable-own-window
- --enable-proc-uptime --enable-mpd --enable-xft --enable-seti
+ --infodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc
+ --localstatedir=/var/lib --enable-xft --enable-seti --enable-dou‐
+ ble-buffer --enable-own-window --enable-proc-uptime --enable-mpd
+ --enable-mldonkey --enable-x11 --enable-portmon --enable-bmpx
+ --enable-xmms=[project]
make
make install # Optional
- ./conky
+ src/conky
- Conky doesn't probably compile with other compilers than gcc and icc.
- It doesn't compile with C89 compiler and not even with pure C99. It
- uses few things that might not exist: strdup(), strcasecmp(), strn-
- casecmp(), optarg variable with getopt() and long long (not in C89).
- Crashes in file system statistics stuff when compiled with icc, I don't
+ Conky probably doesn’t compile with compilers other than gcc and icc.
+ It doesn’t compile with C89 compiler and not even with pure C99. It
+ uses a few things that might not exist: strdup(), strcasecmp(), strn‐
+ casecmp(), optarg variable with getopt() and long long (not in C89).
+ Crashes in file system statistics stuff when compiled with icc, I don’t
know exactly why.
- You can disable 'drawing to own window' feature in case you don't need
+ You can disable ’drawing to own window’ feature in case you don’t need
it by passing --disable-own-window to configure -script.
YOU SHOULD KNOW
- Conky is generally very good on resources. However, certain objects in
- Conky are harder on resources then others. In particular, the $tail,
- $top, $font, and $graph objects are quite costly in comparison to the
+ Conky is generally very good on resources. However, certain objects in
+ Conky are harder on resources then others. In particular, the $tail,
+ $top, $font, and $graph objects are quite costly in comparison to the
rest of Conky.
- If you do use them, please do not complain about memory or CPU usage,
- unless you think something is going seriously wrong (mem leak, et
- cetera).
+ If you do use them, please do not complain about memory or CPU usage,
+ unless you think something’s seriously wrong (mem leak, etc.).
+
+ An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1
+ conky". Saves you the trouble of having to kill and then restart.
+
+ IMPORTANT: For previous Conky users, Conky 1.3 no longer supports the
+ metar stuff. mdsplib was causing way too many problems. Hopefully
+ there’ll be a better solution in Conky 2.x...
OPTIONS
- Command line options override configurations defined in configuration
+ Command line options override configurations defined in configuration
file.
- -V Prints version and exits
+ -v | -V
+ Prints version and exits
-a ALIGNMENT
-t TEXT
- Text to render, remember single quotes, like -t ' $uptime '
+ Text to render, remember single quotes, like -t ’ $uptime ’
-u SECONDS
CONFIGURATION SETTINGS
- Default configuration file is $HOME/.conkyrc (can be changed from
- conky.c among other things). See conkyrc.sample. You might want to copy
- it to $HOME/.conkyrc and then start modifying it.
+ Default configuration file is $HOME/.conkyrc (can be changed from
+ conky.c among other things). See conkyrc.sample. If installing from
+ Debian package, this should be in /usr/share/doc/conky/examples ("gun‐
+ zip conkyrc.sample.gz" to get conkyrc.sample).
+
+ You might want to copy it to $HOME/.conkyrc and then start modifying
+ it. Other configs can be found at http://conky.sf.net
alignment
- Aligned position on screen, may be top_left, top_right, bot-
+ Aligned position on screen, may be top_left, top_right, bot‐
tom_left, bottom_right, or none
background
- Boolean value, if true, Conky will be forked to background when
+ Boolean value, if true, Conky will be forked to background when
started
default_shade_color
- Default shading color and border's shading color
+ Default shading color and border’s shading color
default_outline_color
double_buffer
- Use the Xdbe extension? (eliminates flicker) It is highly recom-
- mended to use own window with this one so double buffer won't be
+ Use the Xdbe extension? (eliminates flicker) It is highly recom‐
+ mended to use own window with this one so double buffer won’t be
so big.
Draw borders around text?
+ draw_graph_borders
+ Draw borders around graphs?
+
+
draw_shades
Draw shades?
font Font name in X, xfontsel can be used to get a nice font
- gap_x Gap between right or left border of screen, same as passing -x
+ gap_x Gap between right or left border of screen, same as passing -x
at command line
- gap_y Gap between top or bottom border of screen, same as passing -y
+ gap_y Gap between top or bottom border of screen, same as passing -y
at command line
Host of MPD server
- mpd_post
+ mpd_port
Port of MPD server
own_window_colour colour
- If own_window_transparent no, set a specified background colour
- (defaults to black). Takes either a hex value (#ffffff) or a
+ If own_window_transparent no, set a specified background colour
+ (defaults to black). Takes either a hex value (#ffffff) or a
valid RGB name (see /usr/lib/X11/rgb.txt)
+ out_to_console
+ Print text to stdout.
+
+
pad_percents
Pad percentages to this many decimals (0 = no padding)
total_run_times
- Total number of times for Conky to update before quitting. Zero
+ Total number of times for Conky to update before quitting. Zero
makes Conky run forever
Use Xft (anti-aliased font and stuff)
- text After this begins text to be formatted on screen
+ min_port_monitors
+ Allow for the creation of at least this number of port monitors
+ (if 0 or not set, default is 16)
+
+
+ min_port_monitor_connections
+ Allow each port monitor to track at least this many connections
+ (if 0 or not set, default is 256)
+
+
+ TEXT After this begins text to be formatted on screen
VARIABLES
- Colors are parsed using XParsecolor(), there might be a list of them:
+ Colors are parsed using XParsecolor(), there might be a list of them:
/usr/X11R6/lib/X11/rgb.txt. Also, http://sedition.com/perl/rgb.html
- [http://sedition.com/perl/rgb.html] Color can be also in #rrggbb format
- (hex). Note that when displaying bytes, power is 1024 and not 1000 so
- 1M really means 1024*1024 bytes and not 1000*1000.
+ [http://sedition.com/perl/rgb.html]. Color can be also in #rrggbb for‐
+ mat (hex). Note that when displaying bytes, power is 1024 and not 1000
+ so 1M really means 1024*1024 bytes and not 1000*1000.
- addr (interface)
+ addr interface
IP address for an interface
Align text to centre
+ apm_adapter
+ Display APM AC adapter status (FreeBSD only)
+
+
+ apm_battery_life
+ Display APM battery life in percent (FreeBSD only)
+
+
+ apm_battery_time
+ Display remaining APM battery life in hh:mm:ss or "unknown" if
+ AC adapterstatus is on-line or charging (FreeBSD only)
+
+
battery (num)
Remaining capacity in ACPI or APM battery. ACPI battery number
can be given as argument (default is BAT0).
+ bmpx_artist
+ Artist in current BMPx track
+
+
+ bmpx_album
+ Album in current BMPx track
+
+
+ bmpx_title
+ Title of the current BMPx track
+
+
+ bmpx_track
+ Track number of the current BMPx track
+
+
+ bmpx_bitrate
+ Bitrate of the current BMPx track
+
+
+ bmpx_uri
+ URI of the current BMPx track
+
+
buffers
Amount of memory buffered
Change drawing color to color
- cpu CPU usage in percents
+ cpu (cpuN)
+ CPU usage in percents. For SMP machines, the CPU number can be
+ provided as an argument. cpu0 is the total usage, and >=cpu1 are
+ individual CPUs.
- cpubar (height),(width)
- Bar that shows CPU usage, height is bar's height in pixels
+ cpubar (cpu number) (height),(width)
+ Bar that shows CPU usage, height is bar’s height in pixels. See
+ $cpu for more info on SMP.
- cpugraph (height),(width) (gradient colour 1) (gradient colour 2)
- CPU usage graph, with optional colours in hex, minus the #.
+ cpugraph (cpu number) (height),(width) (gradient colour 1) (gradient
+ colour 2)
+ CPU usage graph, with optional colours in hex, minus the #. See
+ $cpu for more info on SMP.
diskio Displays current disk IO.
Download speed in kilobytes with one decimal
- downspeedgraph net, (height),(width) (gradient colour 1) (gradient
+ downspeedgraph net (height),(width) (gradient colour 1) (gradient
colour 2) (scale)
Download speed graph, colours defined in hex, minus the #. If
scale is non-zero, it becomes the scale for the graph.
exec command
- Executes a shell command and displays the output in conky. warn-
- ing: this takes a lot more resources than other variables. I'd
+ Executes a shell command and displays the output in conky. warn‐
+ ing: this takes a lot more resources than other variables. I’d
recommend coding wanted behaviour in C and posting a patch.
execi interval command
- Same as exec but with specific interval. Interval can't be less
- than update_interval in configuration.
+ Same as exec but with specific interval. Interval can’t be less
+ than update_interval in configuration. See also $texeci
execibar interval command
File system used space
+ head logfile lines (interval)
+ Displays first N lines of supplied text text file. If interval
+ is not supplied, Conky assumes 2x Conky’s interval. Max of 30
+ lines can be displayed, or until the text buffer is filled.
+
+
hr (height)
Horizontal line, height is the height in pixels
/sys/bus/i2c/devices/ on your local computer.
- if_running (process)
- if PROCESS is running, display everything if_running and the
- matching $endif
+ i8k_ac_status
+ If running the i8k kernel driver for Inspiron laptops, displays
+ whether ac power is on, as listed in /proc/i8k (translated to
+ human-readable). Beware that this is by default not enabled by
+ i8k itself.
- if_existing (file)
- if FILE exists, display everything between if_existing and the
- matching $endif
+ i8k_bios
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the bios version as listed in /proc/i8k.
- if_mounted (mountpoint)
- if MOUNTPOINT is mounted, display everything between if_mounted
- and the matching $endif
+ i8k_buttons_status
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the volume buttons status as listed in /proc/i8k.
- kernel Kernel version
+ i8k_cpu_temp
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the cpu temperature in celsius, as reported by /proc/i8k.
- linkstatus (interface)
- Get the link status for wireless connections
+ i8k_cpu_tempf
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the cpu temperature in farenheit, as reported by /proc/i8k.
- loadavg
- (1,2,3)> System load average, 1 is for past 1 minute, 2 for past
- 5 minutes and 3 for past 15 minutes.
+ i8k_left_fan_rpm
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the left fan’s rate of rotation, in revolutions per minute as
+ listed in /proc/i8k. Beware, some laptops i8k reports these fans
+ in reverse order.
- machine
- Machine, i686 for example
+ i8k_left_fan_status
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the left fan status as listed in /proc/i8k (translated to human-
+ readable). Beware, some laptops i8k reports these fans in
+ reverse order.
- mails Mail count in mail spool. You can use program like fetchmail to
- get mails from some server using your favourite protocol. See
- also new_mails.
+ i8k_right_fan_rpm
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the right fan’s rate of rotation, in revolutions per minute as
+ listed in /proc/i8k. Beware, some laptops i8k reports these fans
+ in reverse order.
- mem Amount of memory in use
+ i8k_right_fan_status
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the right fan status as listed in /proc/i8k (translated to
+ human-readable). Beware, some laptops i8k reports these fans in
+ reverse order.
- membar (height),(width)
- Bar that shows amount of memory in use
+ i8k_serial
+ If running the i8k kernel driver for Inspiron laptops, displays
+ your laptop serial number as listed in /proc/i8k.
- memmax Total amount of memory
+ i8k_version
+ If running the i8k kernel driver for Inspiron laptops, displays
+ the version formatting of /proc/i8k.
- memperc
- Percentage of memory in use
+ if_running (process)
+ if PROCESS is running, display everything if_running and the
+ matching $endif
- ml_upload_counter
- total session upload in mb
+ if_existing (file)
+ if FILE exists, display everything between if_existing and the
+ matching $endif
- ml_download_counter
- total session download in mb
+ if_mounted (mountpoint)
+ if MOUNTPOINT is mounted, display everything between if_mounted
+ and the matching $endif
- ml_nshared_files
- number of shared files
+ kernel Kernel version
+
+
+ linkstatus interface
+ Get the link status for wireless connections
- ml_shared_counter
- total session shared in mb, buggy in some mldonkey versions
+ loadavg
+ (1,2,3)> System load average, 1 is for past 1 minute, 2 for past
+ 5 minutes and 3 for past 15 minutes.
- ml_tcp_upload_rate
- tcp upload rate in kb/s
+ machine
+ Machine, i686 for example
- ml_tcp_download_rate
- tcp download rate in kb/s
+ mails Mail count in mail spool. You can use program like fetchmail to
+ get mails from some server using your favourite protocol. See
+ also new_mails.
- ml_udp_upload_rate
- udp upload rate in kb/s
+ mem Amount of memory in use
- ml_udp_download_rate
- udp download rate in kb/s
+ membar (height),(width)
+ Bar that shows amount of memory in use
- ml_ndownloaded_files
- number of completed files
+ memmax Total amount of memory
- ml_ndownloading_files
- number of downloading files
+ memperc
+ Percentage of memory in use
mpd_artist
mpd_bar (height),(width)
- Bar of mpd's progress
+ Bar of mpd’s progress
mpd_bitrate
mpd_vol
- MPD's volume
+ MPD’s volume
mpd_elapsed
- Song's elapsed time
+ Song’s elapsed time
mpd_length
- Song's length
+ Song’s length
mpd_percent
- Percent of song's progress
+ Percent of song’s progress
+
+
+ mpd_random
+ Random status (On/Off)
+
+
+ mpd_repeat
+ Repeat status (On/Off)
+
+
+ mpd_track
+ Prints the MPD track field
new_mails
System name, Linux for example
+ tcp_portmon port_begin port_end item (index) (ip4 only at present)
+ TCP port monitor for specified local ports. Port numbers must be
+ in the range 1 to 65535. Valid items are:
+
+ count - total number of connections in the range
+
+ rip - remote ip address
+
+ rhost - remote host name
+
+ rport - remote port number
+
+ lip - local ip address
+
+ lhost - local host name
+
+ lservice - local service name from /etc/services
+
+ The connection index provides you with access to each connection
+ in the port monitor. The monitor will return information for
+ index values from 0 to n-1 connections. Values higher than n-1
+ are simply ignored. For the "count" item, the connection index
+ must be omitted. It is required for all other items.
+
+ Examples:
+
+ ${tcp_portmon 6881 6999 count} - displays the number of connec‐
+ tions in the bittorrent port range
+
+ ${tcp_portmon 22 22 rip 0} - displays the remote host ip of the
+ first sshd connection
+
+ ${tcp_portmon 22 22 rip 9} - displays the remote host ip of the
+ tenth sshd connection
+
+ ${tcp_portmon 1 1024 rhost 0} - displays the remote host name of
+ the first connection on a privileged port
+
+ ${tcp_portmon 1 1024 rport 4} - displays the remote host port of
+ the fifth connection on a privileged port
+
+ ${tcp_portmon 1 65535 lservice 14} - displays the local service
+ name of the fifteenth connection in the range of all ports
+
+ Note that port monitor variables which share the same port range
+ actually refer to the same monitor, so many references to a sin‐
+ gle port range for different items and different indexes all use
+ the same monitor internally. In other words, the program avoids
+ creating redundant monitors.
+
+ texeci interval command
+ Runs a command at an interval inside a thread and displays the
+ output. Same as $execi, except the command is run inside a
+ thread. Use this if you have a slow script to keep Conky updat‐
+ ing. You should make the interval slightly longer then the time
+ it takes your script to execute. For example, if you have a
+ script that take 5 seconds to execute, you should make the
+ interval at least 6 seconds. See also $execi.
+
+
offset (pixels)
Move text over by N pixels. See also $voffset.
- tail logfile, lines interval> Displays last N lines of supplied text
- text file. If interval is not supplied, Conky assumes 2x Conky's
- interval. Max of 30 lines. Max of 30 lines can be displayed.
+ tail logfile lines (interval)
+ Displays last N lines of supplied text text file. If interval is
+ not supplied, Conky assumes 2x Conky’s interval. Max of 30 lines
+ can be displayed, or until the text buffer is filled.
time (format)
- Local time, see man strftime to get more information about for-
+ Local time, see man strftime to get more information about for‐
mat
totaldown net
Total download, overflows at 4 GB on Linux with 32-bit arch and
- there doesn't seem to be a way to know how many times it has
+ there doesn’t seem to be a way to know how many times it has
already done that before conky has started.
Upload speed in kilobytes with one decimal
- upspeedgraph net, (height),(width) (gradient colour 1) (gradient colour
+ upspeedgraph net (height),(width) (gradient colour 1) (gradient colour
2) (scale)
Upload speed graph, colours defined in hex, minus the #. If
scale is non-zero, it becomes the scale for the graph.
text to overlap. See also $offset.
+ xmms_bar (height),(width)
+ xmms / bmp / audacious / infopipe: progress bar
+
+
+ xmms_bitrate
+ xmms / bmp / audacious / infopipe: bitrate of current tune
+
+
+ xmms_channels
+ xmms / bmp / audacious / infopipe: number of audio channels of
+ current tune
+
+
+ xmms_filename
+ xmms / bmp / audacious / infopipe: full path and filename of
+ current tune
+
+
+ xmms_frequency
+ xmms / bmp / audacious / infopipe: sampling frequency of current
+ tune
+
+
+ xmms_length
+ xmms / bmp / audacious / infopipe: total length of current tune
+ as MM:SS
+
+
+ xmms_length_seconds
+ xmms / bmp / audacious / infopipe: total length of current tune
+ in seconds
+
+
+ xmms_playlist_position
+ xmms / bmp / audacious / infopipe: playlist position of current
+ tune
+
+
+ xmms_playlist_length
+ xmms / bmp / audacious / infopipe: number of tunes in playlist
+
+
+ xmms_position
+ xmms / bmp / audacious / infopipe: MM:SS position of current
+ tune
+
+
+ xmms_position_seconds
+ xmms / bmp / audacious / infopipe: position of current tune in
+ seconds
+
+
+ xmms_status
+ xmms / bmp / audacious / infopipe: player status (Play‐
+ ing/Paused/Stopped/Not running)
+
+
+ xmms_title
+ xmms / bmp / audacious / infopipe: title of current tune
+
+
EXAMPLES
- conky -t '${time %D %H:%m}' -o -u 30
+ conky -t ’${time %D %H:%m}’ -o -u 30
Start Conky in its own window with date and clock as text and 30
sec update interval.
~/.conkyrc default configuration file
BUGS
- Drawing to root or some other desktop window directly doesn't work with
- all window managers. Especially doesn't work well with Gnome and it has
- been reported that it doesn't work with KDE either. Nautilus can be
- disabled from drawing to desktop with program gconf-editor. Uncheck
- show_desktop in /apps/nautilus/preferences/. There is -w switch in
- Conky to set some specific window id. You might find xwininfo -tree
- useful to find the window to draw to. You can also use -o argument
+ Drawing to root or some other desktop window directly doesn’t work with
+ all window managers. Especially doesn’t work well with Gnome and it has
+ been reported that it doesn’t work with KDE either. Nautilus can be
+ disabled from drawing to desktop with program gconf-editor. Uncheck
+ show_desktop in /apps/nautilus/preferences/. There is -w switch in
+ Conky to set some specific window id. You might find xwininfo -tree
+ useful to find the window to draw to. You can also use -o argument
which makes Conky to create its own window.
SEE ALSO
http://conky.sourceforge.net [http://conky.sourceforge.net]
- http://www.sourceforge.net/projects/conky [http://www.source-
+ http://www.sourceforge.net/projects/conky [http://www.source‐
forge.net/projects/conky]
#conky on irc.freenode.net
AUTHORS
- The Conky dev team. What's up now??!
+ The Conky dev team. What’s up now!
- 2005-08-24 conky(1)
+ 2006-01-01 conky(1)