6 conky - A system monitor for X originally based on the torsmo code, but
7 more kickass. It just keeps on given'er. Yeah.
13 Conky is a system monitor for X originally based on the torsmo code.
14 Since it's original conception, Conky has changed a fair bit from it's
15 predecessor. Conky can display just about anything, either on your
16 root desktop or in it's own window. Conky has many built-in objects,
17 as well as the ability to execute programs and scripts, then display
18 the output from stdout.
20 We are always looking for help, and anyone interested in becoming a
21 developer is welcome. Please use the facilities at SourceForge to make
22 bug reports, feature requests, and submit patches.
24 Thanks for your interest in Conky.
27 For users compiling from source, make sure you have the X development
28 libraries installed. This should be a package along the lines of
29 "libx11-dev or xorg-x11-dev".
31 Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-
32 admin/conky" for installation. There is also usually an up-to-date
33 ebuild within Conky's package or in Svn.
35 Debian,etc. users -- Conky will be in Debian's repositories soon (by
36 mid-September, hopefully), and then Ubuntu shortly thereafter. Until
37 then, "dpkg -i" the .deb package to install.
39 Example to compile and run Conky with all optional components (note
40 that some configure options may differ for your system):
42 sh autogen.sh # Only required if building from Svn
44 ./configure --prefix=/usr --mandir=/usr/share/man
45 --infodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc
46 --localstatedir=/var/lib --enable-xft --enable-seti --enable-dou-
47 ble-buffer --enable-own-window --enable-proc-uptime --enable-mpd
48 --enable-mldonkey --enable-x11 --enable-portmon --enable-xmms
49 --enable-bmp --enable-audacious --enable-infopipe --enable-bmpx
53 make install # Optional
57 Conky probably doesn't compile with compilers other than gcc and icc.
58 It doesn't compile with C89 compiler and not even with pure C99. It
59 uses a few things that might not exist: strdup(), strcasecmp(), strn-
60 casecmp(), optarg variable with getopt() and long long (not in C89).
61 Crashes in file system statistics stuff when compiled with icc, I don't
64 You can disable 'drawing to own window' feature in case you don't need
65 it by passing --disable-own-window to configure -script.
69 Conky is generally very good on resources. However, certain objects in
70 Conky are harder on resources then others. In particular, the $tail,
71 $top, $font, and $graph objects are quite costly in comparison to the
74 If you do use them, please do not complain about memory or CPU usage,
75 unless you think something's seriously wrong (mem leak, etc.).
77 An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1
78 conky". Saves you the trouble of having to kill and then restart.
80 IMPORTANT: For previous Conky users, Conky 1.3 no longer supports the
81 metar stuff. mdsplib was causing way too many problems. Hopefully
82 there'll be a better solution in Conky 2.x...
85 Command line options override configurations defined in configuration
89 Prints version and exits
93 Text alignment on screen, {top,bottom}_{left,right} or none
96 -b Use double buffering (eliminates "flicker")
100 Config file to load instead of $HOME/.conkyrc
103 -d Daemonize Conky, aka fork to background
110 -h Prints command line help and exits
113 -o Create own window to draw
117 Text to render, remember single quotes, like -t ' $uptime '
136 CONFIGURATION SETTINGS
137 Default configuration file is $HOME/.conkyrc (can be changed from
138 conky.c among other things). See conkyrc.sample. If installing from
139 Debian package, this should be in /usr/share/doc/conky/examples ("gun-
140 zip conkyrc.sample.gz" to get conkyrc.sample).
142 You might want to copy it to $HOME/.conkyrc and then start modifying
143 it. Other configs can be found at http://conky.sf.net
146 Aligned position on screen, may be top_left, top_right, bot-
147 tom_left, bottom_right, or none
151 Boolean value, if true, Conky will be forked to background when
156 Set conky on the bottom of all other applications
160 Border margin in pixels
164 Border width in pixels
168 The number of samples to average for CPU monitoring
172 Default color and border color
176 Default shading color and border's shading color
179 default_outline_color
180 Default outline color
184 Use the Xdbe extension? (eliminates flicker) It is highly recom-
185 mended to use own window with this one so double buffer won't be
190 Draw borders around text?
194 Draw borders around graphs?
205 font Font name in X, xfontsel can be used to get a nice font
208 gap_x Gap between right or left border of screen, same as passing -x
212 gap_y Gap between top or bottom border of screen, same as passing -y
217 Substract (file system) buffers from used memory?
221 Mail spool for mail checking
225 Maximum width of window
228 minimum_size width (height)
229 Minimum size of window
233 Allow for the creation of at least this number of port monitors
234 (if 0 or not set, default is 16)
237 min_port_monitor_connections
238 Allow each port monitor to track at least this many connections
239 (if 0 or not set, default is 256)
243 Hostname for mldonkey stuff, defaults to localhost
247 Mldonkey port, 4001 default
251 Mldonkey login, default none
255 Mldonkey password, default none
271 The number of samples to average for net data
275 Force UTF8? requires XFT
279 Boolean, create own window to draw?
282 own_window_transparent
283 Boolean, set pseudo-transparency?
287 if own_window is yes, you may specify type normal, desktop or
288 override (default: normal). Desktop windows are special windows
289 that have no window decorations; are always visible on your
290 desktop; do not appear in your pager or taskbar; and are sticky
291 across all workspaces. Override windows are not under the con-
292 trol of the window manager. Hints are ignored. This type of win-
293 dow can be useful for certain situations.
296 own_window_colour colour
297 If own_window_transparent no, set a specified background colour
298 (defaults to black). Takes either a hex value (#ffffff) or a
299 valid RGB name (see /usr/lib/X11/rgb.txt)
302 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
303 If own_window is yes, you may use these window manager hints to
304 affect the way conky displays. Notes: Use own_window_type desk-
305 top as another way to implement many of these hints implicitly.
306 If you use own_window_type override, window manager hints have
307 no meaning and are ignored.
311 Print text to stdout.
315 Pad percentages to this many decimals (0 = no padding)
319 Border stippling (dashing) in pixels
323 Total number of times for Conky to update before quitting. Zero
324 makes Conky run forever
328 Update interval in seconds
332 Boolean value, if true, text is rendered in upper case
336 Adds spaces after certain objects to stop them from moving other
337 things around. Note that this only helps if you are using a mono
338 font, such as Bitstream Vera Sans Mono.
342 Use Xft (anti-aliased font and stuff)
346 Manually set the WM_CLASS name. Defaults to "conky".
350 Alpha of Xft font. Must be a value at or between 1 and 0.
358 Use specified player/plugin for the xmms status variables. Valid
359 items are: none, xmms, bmp, audacious and infopipe. (default is
360 none). Note that bmpx is currently handled separately.
363 TEXT After this begins text to be formatted on screen
367 Colors are parsed using XParsecolor(), there might be a list of them:
368 /usr/X11R6/lib/X11/rgb.txt. Also, http://sedition.com/perl/rgb.html
369 [http://sedition.com/perl/rgb.html]. Color can be also in #rrggbb for-
370 mat (hex). Note that when displaying bytes, power is 1024 and not 1000
371 so 1M really means 1024*1024 bytes and not 1000*1000.
374 IP address for an interface
378 ACPI ac adapter state.
386 ACPI temperature in C.
390 ACPI temperature in F.
394 CPU temperature from therm_adt746x
398 Fan speed from therm_adt746x
402 Right-justify text, with space of N
410 Display APM AC adapter status (FreeBSD only)
414 Display APM battery life in percent (FreeBSD only)
418 Display remaining APM battery life in hh:mm:ss or "unknown" if
419 AC adapterstatus is on-line or charging (FreeBSD only)
423 Remaining capacity in ACPI or APM battery. ACPI battery number
424 can be given as argument (default is BAT0).
428 Artist in current BMPx track
432 Album in current BMPx track
436 Title of the current BMPx track
440 Track number of the current BMPx track
444 Bitrate of the current BMPx track
448 URI of the current BMPx track
452 Amount of memory buffered
455 cached Amount of memory cached
459 Change drawing color to color
463 CPU usage in percents. For SMP machines, the CPU number can be
464 provided as an argument. cpu0 is the total usage, and >=cpu1 are
468 cpubar (cpu number) (height),(width)
469 Bar that shows CPU usage, height is bar's height in pixels. See
470 $cpu for more info on SMP.
473 cpugraph (cpu number) (height),(width) (gradient colour 1) (gradient
475 CPU usage graph, with optional colours in hex, minus the #. See
476 $cpu for more info on SMP.
479 diskio Displays current disk IO.
482 diskiograph (height),(width) (gradient colour 1) (gradient colour 2)
484 Disk IO graph, colours defined in hex, minus the #. If scale is
485 non-zero, it becomes the scale for the graph.
489 Download speed in kilobytes
493 Download speed in kilobytes with one decimal
496 downspeedgraph net (height),(width) (gradient colour 1) (gradient
498 Download speed graph, colours defined in hex, minus the #. If
499 scale is non-zero, it becomes the scale for the graph.
502 else Text to show if any of the above are not true
506 Executes a shell command and displays the output in conky. warn-
507 ing: this takes a lot more resources than other variables. I'd
508 recommend coding wanted behaviour in C and posting a patch.
512 Same as exec, except if the first value return is a value
513 between 0-100, it will use that number for a bar. The size for
514 the bar is currently fixed, but that may change in the future.
518 Same as execbar, but graphs values.
521 execi interval command
522 Same as exec but with specific interval. Interval can't be less
523 than update_interval in configuration. See also $texeci
526 execibar interval command
527 Same as execbar, except with an interval
530 execigraph interval command
531 Same as execigraph, but takes an interval arg graphs values
535 Specify a different font. Only applies to one line.
538 freq Returns CPU frequency in MHz
541 freq_g Returns CPU frequency in GHz
545 Returns CPU frequency in MHz, but is calculated by counting to
546 clock cycles to complete an instruction. Only available for
551 Returns CPU frequency in GHz, but is calculated by counting to
552 clock cycles to complete an instruction. Only available for
556 fs_bar (height),(width) fs
557 Bar that shows how much space is used on a file system. height
558 is the height in pixels. fs is any file on that file system.
562 Free space on a file system available for users.
566 Free percentage of space on a file system available for users.
574 File system used space
577 head logfile lines (interval)
578 Displays first N lines of supplied text text file. If interval
579 is not supplied, Conky assumes 2x Conky's interval. Max of 30
580 lines can be displayed, or until the text buffer is filled.
584 Horizontal line, height is the height in pixels
588 I2C sensor from sysfs (Linux 2.6). dev may be omitted if you
589 have only one I2C device. type is either in (or vol) meaning
590 voltage, fan meaning fan or temp/tempf (first in C, second in F)
591 meaning temperature. n is number of the sensor. See
592 /sys/bus/i2c/devices/ on your local computer.
596 If running the i8k kernel driver for Inspiron laptops, displays
597 whether ac power is on, as listed in /proc/i8k (translated to
598 human-readable). Beware that this is by default not enabled by
603 If running the i8k kernel driver for Inspiron laptops, displays
604 the bios version as listed in /proc/i8k.
608 If running the i8k kernel driver for Inspiron laptops, displays
609 the volume buttons status as listed in /proc/i8k.
613 If running the i8k kernel driver for Inspiron laptops, displays
614 the cpu temperature in Celsius, as reported by /proc/i8k.
618 If running the i8k kernel driver for Inspiron laptops, displays
619 the cpu temperature in Farenheit, as reported by /proc/i8k.
623 If running the i8k kernel driver for Inspiron laptops, displays
624 the left fan's rate of rotation, in revolutions per minute as
625 listed in /proc/i8k. Beware, some laptops i8k reports these fans
630 If running the i8k kernel driver for Inspiron laptops, displays
631 the left fan status as listed in /proc/i8k (translated to human-
632 readable). Beware, some laptops i8k reports these fans in
637 If running the i8k kernel driver for Inspiron laptops, displays
638 the right fan's rate of rotation, in revolutions per minute as
639 listed in /proc/i8k. Beware, some laptops i8k reports these fans
644 If running the i8k kernel driver for Inspiron laptops, displays
645 the right fan status as listed in /proc/i8k (translated to
646 human-readable). Beware, some laptops i8k reports these fans in
651 If running the i8k kernel driver for Inspiron laptops, displays
652 your laptop serial number as listed in /proc/i8k.
656 If running the i8k kernel driver for Inspiron laptops, displays
657 the version formatting of /proc/i8k.
661 if PROCESS is running, display everything if_running and the
666 if FILE exists, display everything between if_existing and the
670 if_mounted (mountpoint)
671 if MOUNTPOINT is mounted, display everything between if_mounted
672 and the matching $endif
675 kernel Kernel version
679 Get the link status for wireless connections
683 (1,2,3)> System load average, 1 is for past 1 minute, 2 for past
684 5 minutes and 3 for past 15 minutes.
688 Machine, i686 for example
691 mails Mail count in mail spool. You can use program like fetchmail to
692 get mails from some server using your favourite protocol. See
696 mem Amount of memory in use
699 membar (height),(width)
700 Bar that shows amount of memory in use
703 memmax Total amount of memory
707 Percentage of memory in use
711 Artist in current MPD song must be enabled at compile
715 Album in current MPD song
718 mpd_bar (height),(width)
719 Bar of mpd's progress
723 Bitrate of current song
727 Playing, stopped, et cetera.
731 Title of current MPD song
747 Percent of song's progress
751 Random status (On/Off)
755 Repeat status (On/Off)
759 Prints the MPD track field
763 Prints the MPD name field
767 Prints the file name of the current MPD song
771 Prints the song name in either the form "artist - title" or file
772 name, depending on whats available
776 Unread mail count in mail spool.
788 If running on Apple powerbook/ibook, display information on bat-
789 tery status. The item parameter specifies, what information to
790 display. Exactly one item must be specified. Valid items are:
792 status: Display if battery is fully charged, charging, discharg-
793 ing or absent (running on AC)
795 percent: Display charge of battery in percent, if charging or
796 discharging. Nothing will be displayed, if battery is fully
799 time: Display the time remaining until the battery will be fully
800 charged or discharged at current rate. Nothing is displayed, if
801 battery is absent or if it's present but fully charged and not
805 pre_exec shell command
806 Executes a shell command one time before conky displays anything
807 and puts output as text.
811 Total processes (sleeping and running)
815 Running processes (not sleeping), requires Linux 2.6
823 Stippled (dashed) horizontal line
826 swapbar (height),(width)
827 Bar that shows amount of swap in use
830 swap Amount of swap in use
838 Percentage of swap in use
842 System name, Linux for example
845 tcp_portmon port_begin port_end item (index) (ip4 only at present)
846 TCP port monitor for specified local ports. Port numbers must be
847 in the range 1 to 65535. Valid items are:
849 count - total number of connections in the range
851 rip - remote ip address
853 rhost - remote host name
855 rport - remote port number
857 rservice - remote service name from /etc/services
859 lip - local ip address
861 lhost - local host name
863 lport - local port number
865 lservice - local service name from /etc/services
867 The connection index provides you with access to each connection
868 in the port monitor. The monitor will return information for
869 index values from 0 to n-1 connections. Values higher than n-1
870 are simply ignored. For the "count" item, the connection index
871 must be omitted. It is required for all other items.
875 ${tcp_portmon 6881 6999 count} - displays the number of connec-
876 tions in the bittorrent port range
878 ${tcp_portmon 22 22 rip 0} - displays the remote host ip of the
879 first sshd connection
881 ${tcp_portmon 22 22 rip 9} - displays the remote host ip of the
882 tenth sshd connection
884 ${tcp_portmon 1 1024 rhost 0} - displays the remote host name of
885 the first connection on a privileged port
887 ${tcp_portmon 1 1024 rport 4} - displays the remote host port of
888 the fifth connection on a privileged port
890 ${tcp_portmon 1 65535 lservice 14} - displays the local service
891 name of the fifteenth connection in the range of all ports
893 Note that port monitor variables which share the same port range
894 actually refer to the same monitor, so many references to a sin-
895 gle port range for different items and different indexes all use
896 the same monitor internally. In other words, the program avoids
897 creating redundant monitors.
899 texeci interval command
900 Runs a command at an interval inside a thread and displays the
901 output. Same as $execi, except the command is run inside a
902 thread. Use this if you have a slow script to keep Conky updat-
903 ing. You should make the interval slightly longer then the time
904 it takes your script to execute. For example, if you have a
905 script that take 5 seconds to execute, you should make the
906 interval at least 6 seconds. See also $execi.
910 Move text over by N pixels. See also $voffset.
913 tail logfile lines (interval)
914 Displays last N lines of supplied text text file. If interval is
915 not supplied, Conky assumes 2x Conky's interval. Max of 30 lines
916 can be displayed, or until the text buffer is filled.
920 Local time, see man strftime to get more information about for-
925 Total download, overflows at 4 GB on Linux with 32-bit arch and
926 there doesn't seem to be a way to know how many times it has
927 already done that before conky has started.
931 This takes arguments in the form:top (name) (number) Basically,
932 processes are ranked from highest to lowest in terms of cpu
933 usage, which is what (num) represents. The types are: "name",
934 "pid", "cpu", and mem". There can be a max of 10 processes
939 Same as top, except sorted by mem usage instead of cpu
943 Total upload, this one too, may overflow
946 updates Number of updates
951 Upload speed in kilobytes
955 Upload speed in kilobytes with one decimal
958 upspeedgraph net (height),(width) (gradient colour 1) (gradient colour
960 Upload speed graph, colours defined in hex, minus the #. If
961 scale is non-zero, it becomes the scale for the graph.
968 Uptime in a shorter format
972 Seti@home current progress
975 seti_progbar (height),(width)
976 Seti@home current progress bar
980 Seti@home total user credit
984 Change vertical offset by N pixels. Negative values will cause
985 text to overlap. See also $offset.
988 xmms_bar (height),(width)
989 xmms / bmp / audacious / infopipe: progress bar
993 xmms / bmp / audacious / infopipe: bitrate of current tune
997 xmms / bmp / audacious / infopipe: number of audio channels of
1002 xmms / bmp / audacious / infopipe: full path and filename of
1007 xmms / bmp / audacious / infopipe: sampling frequency of current
1012 xmms / bmp / audacious / infopipe: total length of current tune
1017 xmms / bmp / audacious / infopipe: total length of current tune
1021 xmms_playlist_position
1022 xmms / bmp / audacious / infopipe: playlist position of current
1026 xmms_playlist_length
1027 xmms / bmp / audacious / infopipe: number of tunes in playlist
1031 xmms / bmp / audacious / infopipe: MM:SS position of current
1035 xmms_position_seconds
1036 xmms / bmp / audacious / infopipe: position of current tune in
1041 xmms / bmp / audacious / infopipe: player status (Play-
1042 ing/Paused/Stopped/Not running)
1046 xmms / bmp / audacious / infopipe: title of current tune
1050 If running the IBM ACPI, displays the fan speed.
1054 If running the IBM ACPI, displays the temperatures from the IBM
1055 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
1060 If running the IBM ACPI, displays the "master" volume, con-
1061 trolled by the volume keys (0-14).
1065 If running the IBM ACPI, displays the brigtness of the laptops's
1070 conky -t '${time %D %H:%m}' -o -u 30
1071 Start Conky in its own window with date and clock as text and 30
1072 sec update interval.
1074 conky -a top_left -x 5 -y 500 -d
1075 Start Conky to background at coordinates (5, 500).
1078 ~/.conkyrc default configuration file
1081 Drawing to root or some other desktop window directly doesn't work with
1082 all window managers. Especially doesn't work well with Gnome and it has
1083 been reported that it doesn't work with KDE either. Nautilus can be
1084 disabled from drawing to desktop with program gconf-editor. Uncheck
1085 show_desktop in /apps/nautilus/preferences/. There is -w switch in
1086 Conky to set some specific window id. You might find xwininfo -tree
1087 useful to find the window to draw to. You can also use -o argument
1088 which makes Conky to create its own window.
1091 http://conky.sourceforge.net [http://conky.sourceforge.net]
1093 http://www.sourceforge.net/projects/conky [http://www.source-
1094 forge.net/projects/conky]
1096 #conky on irc.freenode.net
1099 The Conky dev team. What's up now!