1conky(1) conky(1)
2
6 conky - A system monitor for X originally based on the torsmo code, but
7 more kickass. It just keeps on given'er. Yeah.
8
10 conky [options]
11
13 Conky is a system monitor for X originally based on torsmo. Since it's
14 conception, Conky has changed significantly from it's predecessor.
15 Conky can display just about anything, either on your root desktop or
16 in it's own window. Conky has many built-in objects, as well as the
17 ability to execute programs and scripts, then display the output from
18 stdout.
19 We are always looking for help, and anyone interested in becoming a de‐
21 veloper is welcome. Please use the facilities at SourceForge to make
22 bug reports, feature requests, and submit patches.
23 Thanks for your interest in Conky.
25
27 For users compiling from source on a binary distro, make sure you have
28 the X development libraries installed. This should be a package along
29 the lines of "libx11-dev" or "xorg-x11-dev" for X11 libs, and similar
30 "-dev" format for the other libs required (depending on your configure
31 options).
32 Conky has (for some time) been available in the repositories of most
34 popular distributions. Here are some installation instructions for a
35 few:
36 Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-
38 admin/conky" for installation. There is also usually an up-to-date
39 ebuild within Conky's package or in SVN.
40 Debian, etc. users -- Conky should be in your repositories, and can be
42 installed by doing "aptitude install conky".
43 Example to compile and run Conky with all optional components (note
45 that some configure options may differ for your system):
46 sh autogen.sh # Only required if building from SVN
48 ./configure --prefix=/usr --mandir=/usr/share/man --in‐
50 fodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc --local‐
51 statedir=/var/lib --disable-own-window --enable-audacious[=yes|no|lega‐
52 cy] --enable-bmpx --disable-hddtemp --disable-mpd --enable-xmms2 --dis‐
53 able-portmon --disable-network --enable-debug --disable-x11 --dis‐
54 able-double-buffer --disable-xdamage --disable-xft
55 make
57 make install # Optional
59 src/conky
61 Conky has been tested to be compatible with C99 C, however it has not
63 been tested with anything other than gcc, and is not guaranteed to work
64 with other compilers.
65
67 Conky is generally very good on resources. That said, the more you try
68 to make Conky do, the more resources it is going to consume.
69 An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1
71 conky". Saves you the trouble of having to kill and then restart. You
72 can now also do the same with SIGHUP.
73
75 Command line options override configurations defined in configuration
76 file.
77 -v | -V | --verbose
79 Prints version and exits
80 -a | --alignment=ALIGNMENT
83 Text alignment on screen, {top,bottom}_{left,right} or none
84 -b | --double-buffer
87 Use double buffering (eliminates "flicker")
88 -c | --config=FILE
91 Config file to load instead of $HOME/.conkyrc
92 -d | --daemonize
95 Daemonize Conky, aka fork to background
96 -f | --font=FONT
99 Font to use
100 -h | --help
103 Prints command line help and exits
104 -o | --own-window
107 Create own window to draw
108 -t | --text=TEXT
111 Text to render, remember single quotes, like -t ' $uptime '
112 -u | --interval=SECONDS
115 Update interval
116 -w | --window-id=WIN_ID
119 Window id to draw
120 -x X_COORDINATE
123 X position
124 -y Y_COORDINATE
127 Y position
128
131 Default configuration file location is $HOME/.conkyrc or
132 ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc,
133 and you can find the sample config file there (/etc/conky/conky.conf).
134 You might want to copy it to $HOME/.conkyrc and then start modifying
136 it. Other configs can be found at http://conky.sf.net/
137 alignment
139 Aligned position on screen, may be top_left, top_right, top_mid‐
140 dle, bottom_left, bottom_right, bottom_middle, middle_left, mid‐
141 dle_right, or none (also can be abreviated as tl, tr, tm, bl,
142 br, bm, ml, mr)
143 background
146 Boolean value, if true, Conky will be forked to background when
147 started
148 border_margin
151 Border margin in pixels
152 border_width
155 Border width in pixels
156 color0 A color variable for use inside TEXT segments
159 color1 A color variable for use inside TEXT segments
162 color2 A color variable for use inside TEXT segments
165 color3 A color variable for use inside TEXT segments
168 color4 A color variable for use inside TEXT segments
171 color5 A color variable for use inside TEXT segments
174 color6 A color variable for use inside TEXT segments
177 color7 A color variable for use inside TEXT segments
180 color8 A color variable for use inside TEXT segments
183 color9 A color variable for use inside TEXT segments
186 cpu_avg_samples
189 The number of samples to average for CPU monitoring
190 top_cpu_separate
193 If true, cpu in top will show usage of one processor's power. If
194 false, cpu in top will show the usage of all processors' power
195 combined.
196 default_color
199 Default color and border color
200 default_outline_color
203 Default outline color
204 default_shade_color
207 Default shading color and border's shading color
208 double_buffer
211 Use the Xdbe extension? (eliminates flicker) It is highly recom‐
212 mended to use own window with this one so double buffer won't be
213 so big.
214 draw_borders
217 Draw borders around text?
218 draw_graph_borders
221 Draw borders around graphs?
222 draw_outline
225 Draw outlines?
226 draw_shades
229 Draw shades?
230 font Font name in X, xfontsel can be used to get a nice font
233 gap_x Gap, in pixels, between right or left border of screen, same as
236 passing -x at command line, e.g. gap_x 10
237 gap_y Gap, in pixels, between top or bottom border of screen, same as
240 passing -y at command line, e.g. gap_y 10.
241 imap Default global IMAP server. Arguments are: "host user pass [-i
244 interval] [-f folder] [-p port] [-e command]". Default port is
245 143, default folder is 'INBOX', default interval is 5 minutes.
246 If the password is supplied as '*', you will be prompted to en‐
247 ter the password when Conky starts.
248 mail_spool
251 Mail spool for mail checking
252 max_port_monitor_connections
255 Allow each port monitor to track at most this many connections
256 (if 0 or not set, default is 256)
257 max_specials
260 Maximum number of special things, e.g. fonts, offsets, aligns,
261 etc. (default is 512)
262 max_user_text bytes
265 Maximum size of user text buffer, i.e. layout below TEXT line in
266 config file (default is 16384 bytes)
267 text_buffer_size bytes
270 Size of the standard text buffer (default is 128 bytes). This
271 buffer is used for intermediary text, such as individual lines,
272 output from $exec vars, and various other variables. Increasing
273 the size of this buffer can drastically reduce Conky's perfor‐
274 mance, but will allow for more text display per variable. The
275 size of this buffer cannot be smaller than the default value of
276 128 bytes.
277 maximum_width pixels
280 Maximum width of window
281 minimum_size width (height)
284 Minimum size of window
285 mpd_host
288 Host of MPD server
289 mpd_port
292 Port of MPD server
293 mpd_password
296 MPD server password
297 music_player_interval
300 Music player thread update interval (defaults to Conky's update
301 interval)
302 net_avg_samples
305 The number of samples to average for net data
306 no_buffers
309 Substract (file system) buffers from used memory?
310 override_utf8_locale
313 Force UTF8? requires XFT
314 own_window
317 Boolean, create own window to draw?
318 own_window_class
321 Manually set the WM_CLASS name. Defaults to "Conky".
322 own_window_colour colour
325 If own_window_transparent no, set a specified background colour
326 (defaults to black). Takes either a hex value (#ffffff) or a
327 valid RGB name (see /usr/lib/X11/rgb.txt)
328 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
331 If own_window is yes, you may use these window manager hints to
332 affect the way Conky displays. Notes: Use own_window_type desk‐
333 top as another way to implement many of these hints implicitly.
334 If you use own_window_type override, window manager hints have
335 no meaning and are ignored.
336 own_window_title
339 Manually set the window name. Defaults to "<hostname> - conky".
340 own_window_transparent
343 Boolean, set pseudo-transparency?
344 own_window_type
347 if own_window is yes, you may specify type normal, desktop or
348 override (default: normal). Desktop windows are special windows
349 that have no window decorations; are always visible on your
350 desktop; do not appear in your pager or taskbar; and are sticky
351 across all workspaces. Override windows are not under the con‐
352 trol of the window manager. Hints are ignored. This type of win‐
353 dow can be useful for certain situations.
354 out_to_console
357 Print text to stdout.
358 pad_percents
361 Pad percentages to this many decimals (0 = no padding)
362 pop3 Default global POP3 server. Arguments are: "host user pass [-i
365 interval] [-p port] [-e command]". Default port is 110, default
366 interval is 5 minutes. If the password is supplied as '*', you
367 will be prompted to enter the password when Conky starts.
368 short_units
371 Shortens units to a single character (kiB->k, GiB->G, etc.). De‐
372 fault is off.
373 stippled_borders
376 Border stippling (dashing) in pixels
377 total_run_times
380 Total number of times for Conky to update before quitting. Zero
381 makes Conky run forever
382 update_interval
385 Update interval in seconds
386 uppercase
389 Boolean value, if true, text is rendered in upper case
390 use_spacer
393 Adds spaces around certain objects to stop them from moving oth‐
394 er things around. Arguments are left, right, and none (default).
395 The old true/false values are deprecated and default to
396 right/none respectively. Note that this only helps if you are
397 using a mono font, such as Bitstream Vera Sans Mono.
398 use_xft
401 Use Xft (anti-aliased font and stuff)
402 xftalpha
405 Alpha of Xft font. Must be a value at or between 1 and 0.
406 xftfont
409 Xft font to use.
410 TEXT After this begins text to be formatted on screen
413
416 Colors are parsed using XParsecolor(), there might be a list of them:
417 /usr/share/X11/rgb.txt. Also, ⟨http://sedition.com/perl/rgb.html⟩.
418 Color can be also in #rrggbb format (hex).
419 addr interface
421 IP address for an interface
422 addrs interface
425 IP addresses for an interface (if one - works like addr). Linux
426 only.
427 acpiacadapter
430 ACPI ac adapter state.
431 acpifan
434 ACPI fan state
435 acpitemp
438 ACPI temperature in C.
439 acpitempf
442 ACPI temperature in F.
443 adt746xcpu
446 CPU temperature from therm_adt746x
447 adt746xfan
450 Fan speed from therm_adt746x
451 alignr (num)
454 Right-justify text, with space of N
455 alignc (num)
458 Align text to centre
459 apm_adapter
462 Display APM AC adapter status (FreeBSD only)
463 apm_battery_life
466 Display APM battery life in percent (FreeBSD only)
467 apm_battery_time
470 Display remaining APM battery life in hh:mm:ss or "unknown" if
471 AC adapterstatus is on-line or charging (FreeBSD only)
472 audacious_bar (height),(width)
475 Progress bar
476 audacious_bitrate
479 Bitrate of current tune
480 audacious_channels
483 Number of audio channels of current tune
484 audacious_filename
487 Full path and filename of current tune
488 audacious_frequency
491 Sampling frequency of current tune
492 audacious_length
495 Total length of current tune as MM:SS
496 audacious_length_seconds
499 Total length of current tune in seconds
500 audacious_playlist_position
503 Playlist position of current tune
504 audacious_playlist_length
507 Number of tunes in playlist
508 audacious_position
511 Position of current tune (MM:SS)
512 audacious_position_seconds
515 Position of current tune in seconds
516 audacious_status
519 Player status (Playing/Paused/Stopped/Not running)
520 audacious_title (max length)
523 Title of current tune with optional maximum length specifier
524 battery (num)
527 Battery status and remaining percentage capacity of ACPI or APM
528 battery. ACPI battery number can be given as argument (default
529 is BAT0).
530 battery_bar (height),(width) (num)
533 Battery percentage remaining of ACPI battery in a bar. ACPI bat‐
534 tery number can be given as argument (default is BAT0).
535 battery_percent (num)
538 Battery percentage remaining for ACPI battery. ACPI battery num‐
539 ber can be given as argument (default is BAT0).
540 battery_time (num)
543 Battery charge/discharge time remaining of ACPI battery. ACPI
544 battery number can be given as argument (default is BAT0).
545 bmpx_artist
548 Artist in current BMPx track
549 bmpx_album
552 Album in current BMPx track
553 bmpx_title
556 Title of the current BMPx track
557 bmpx_track
560 Track number of the current BMPx track
561 bmpx_bitrate
564 Bitrate of the current BMPx track
565 bmpx_uri
568 URI of the current BMPx track
569 buffers
572 Amount of memory buffered
573 cached Amount of memory cached
576 color (color)
579 Change drawing color to color
580 color0 Change drawing color to color0 configuration option
583 color1 Change drawing color to color1 configuration option
586 color2 Change drawing color to color2 configuration option
589 color3 Change drawing color to color3 configuration option
592 color4 Change drawing color to color4 configuration option
595 color5 Change drawing color to color5 configuration option
598 color6 Change drawing color to color6 configuration option
601 color7 Change drawing color to color7 configuration option
604 color8 Change drawing color to color8 configuration option
607 color9 Change drawing color to color9 configuration option
610 conky_version
613 Conky version
614 conky_build_date
617 Date Conky was built
618 conky_bulid_arch
621 CPU architecture Conky was built for
622 cpu (cpuN)
625 CPU usage in percents. For SMP machines, the CPU number can be
626 provided as an argument. ${cpu cpu0} is the total usage, and
627 ${cpu cpuX} (X >= 1) are individual CPUs.
628 cpubar (cpu number) (height),(width)
631 Bar that shows CPU usage, height is bar's height in pixels. See
632 $cpu for more info on SMP.
633 cpugraph (cpu number) (height),(width) (gradient colour 1) (gradient
636 colour 2)
637 CPU usage graph, with optional colours in hex, minus the #. See
638 $cpu for more info on SMP.
639 diskio (device)
642 Displays current disk IO. Device is optional, and takes the form
643 of sda for /dev/sda. Individual partitions are allowed.
644 diskiograph (device) (height),(width) (gradient colour 1) (gradient
647 colour 2) (scale)
648 Disk IO graph, colours defined in hex, minus the #. If scale is
649 non-zero, it becomes the scale for the graph.
650 diskio_read (device)
653 Displays current disk IO for reads. Device as in diskio.
654 diskiograph_read (device) (height),(width) (gradient colour 1) (gradi‐
657 ent colour 2) (scale)
658 Disk IO graph for reads, colours defined in hex, minus the #. If
659 scale is non-zero, it becomes the scale for the graph. Device as
660 in diskio.
661 diskio_write (device)
664 Displays current disk IO for writes. Device as in diskio.
665 diskiograph_write (device) (height),(width) (gradient colour 1) (gradi‐
668 ent colour 2) (scale)
669 Disk IO graph for writes, colours defined in hex, minus the #.
670 If scale is non-zero, it becomes the scale for the graph. Device
671 as in diskio.
672 disk_protect device
675 Disk protection status, if supported (needs kernel-patch).
676 Prints either "frozen" or "free " (note the padding).
677 downspeed net
680 Download speed in kilobytes
681 downspeedf net
684 Download speed in kilobytes with one decimal
685 downspeedgraph net (height),(width) (gradient colour 1) (gradient
688 colour 2) (scale)
689 Download speed graph, colours defined in hex, minus the #. If
690 scale is non-zero, it becomes the scale for the graph.
691 else Text to show if any of the above are not true
694 entropy_avail
697 Current entropy available for crypto freaks
698 entropy_bar (height),(width)
701 Normalized bar of available entropy for crypto freaks
702 entropy_poolsize
705 Total size of system entropy pool for crypto freaks
706 exec command
709 Executes a shell command and displays the output in conky. warn‐
710 ing: this takes a lot more resources than other variables. I'd
711 recommend coding wanted behaviour in C and posting a patch.
712 execbar command
715 Same as exec, except if the first value return is a value be‐
716 tween 0-100, it will use that number for a bar. The size for the
717 bar is currently fixed, but that may change in the future.
718 execgraph command
721 Same as execbar, but graphs values.
722 execi interval command
725 Same as exec but with specific interval. Interval can't be less
726 than update_interval in configuration. See also $texeci
727 execibar interval command
730 Same as execbar, except with an interval
731 execigraph interval command
734 Same as execgraph, but takes an interval arg graphs values
735 execp command
738 Executes a shell command and displays the output in conky. warn‐
739 ing: this takes a lot more resources than other variables. I'd
740 recommend coding wanted behaviour in C and posting a patch. This
741 differs from $exec in that it parses the output of the command,
742 so you can insert things like ${color red}hi!${color} in your
743 script and have it correctly parsed by Conky. Caveats: Conky
744 parses and evaluates the output of $execp every time Conky
745 loops, and then destroys all the objects. If you try to use any‐
746 thing like $execi within an $execp statement, it will function‐
747 ally run at the same interval that the $execp statement runs, as
748 it is created and destroyed at every interval.
749 execpi interval command
752 Same as execp but with specific interval. Interval can't be less
753 than update_interval in configuration. Note that the output from
754 the $execpi command is still parsed and evaluated at every in‐
755 terval.
756 font (font)
759 Specify a different font. This new font will apply to the cur‐
760 rent line and everything following. You can use a $font with no
761 arguments to change back to the default font (much like with
762 $color)
763 freq (n)
766 Returns CPU #n's frequency in MHz. CPUs are counted from 1. If
767 omitted, the parameter defaults to 1.
768 freq_g (n)
771 Returns CPU #n's frequency in GHz. CPUs are counted from 1. If
772 omitted, the parameter defaults to 1.
773 freq_dyn
776 Returns CPU frequency in MHz, but is calculated by counting to
777 clock cycles to complete an instruction. Only available for
778 x86/amd64.
779 freq_dyn_g
782 Returns CPU frequency in GHz, but is calculated by counting to
783 clock cycles to complete an instruction. Only available for
784 x86/amd64.
785 fs_bar (height),(width) fs
788 Bar that shows how much space is used on a file system. height
789 is the height in pixels. fs is any file on that file system.
790 fs_free (fs)
793 Free space on a file system available for users.
794 fs_free_perc (fs)
797 Free percentage of space on a file system available for users.
798 fs_size (fs)
801 File system size
802 fs_type (fs)
805 File system type
806 fs_used (fs)
809 File system used space
810 goto x The next element will be printed at position 'x'.
813 gw_iface
816 Displays the default route's interface or "multiple"/"none" ac‐
817 cordingly.
818 gw_ip Displays the default gateway's IP or "multiple"/"none" accord‐
821 ingly.
822 hddtemp dev, (host,(port))
825 Displays temperature of a selected hard disk drive as reported
826 by the hddtemp daemon running on host:port. Default host is
827 127.0.0.1, default port is 7634.
828 head logfile lines (interval)
831 Displays first N lines of supplied text text file. If interval
832 is not supplied, Conky assumes 2x Conky's interval. Max of 30
833 lines can be displayed, or until the text buffer is filled.
834 hr (height)
837 Horizontal line, height is the height in pixels
838 hwmon (dev) type n
841 Hwmon sensor from sysfs (Linux 2.6). Parameter dev may be omit‐
842 ted if you have only one hwmon device. Parameter type is either
843 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' (Cel‐
844 sius) or 'tempf' (Fahrenheit) meaning temperature. Parameter n
845 is number of the sensor. See /sys/class/hwmon/ on your local
846 computer.
847 iconv_start codeset_from codeset_to
850 Convert text from one codeset to another using GNU iconv. Needs
851 to be stopped with iconv_stop.
852 iconv_stop
855 Stop iconv codeset conversion.
856 i2c (dev) type n
859 I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted
860 if you have only one I2C device. Parameter type is either 'in'
861 or 'vol' meaning voltage; 'fan' meaning fan; 'temp' (Celsius) or
862 'tempf' (Fahrenheit) meaning temperature. Parameter n is number
863 of the sensor. See /sys/bus/i2c/devices/ on your local computer.
864 i8k_ac_status
867 If running the i8k kernel driver for Inspiron laptops, displays
868 whether ac power is on, as listed in /proc/i8k (translated to
869 human-readable). Beware that this is by default not enabled by
870 i8k itself.
871 i8k_bios
874 If running the i8k kernel driver for Inspiron laptops, displays
875 the bios version as listed in /proc/i8k.
876 i8k_buttons_status
879 If running the i8k kernel driver for Inspiron laptops, displays
880 the volume buttons status as listed in /proc/i8k.
881 i8k_cpu_temp
884 If running the i8k kernel driver for Inspiron laptops, displays
885 the cpu temperature in Celsius, as reported by /proc/i8k.
886 i8k_cpu_tempf
889 If running the i8k kernel driver for Inspiron laptops, displays
890 the cpu temperature in Fahrenheit, as reported by /proc/i8k.
891 i8k_left_fan_rpm
894 If running the i8k kernel driver for Inspiron laptops, displays
895 the left fan's rate of rotation, in revolutions per minute as
896 listed in /proc/i8k. Beware, some laptops i8k reports these fans
897 in reverse order.
898 i8k_left_fan_status
901 If running the i8k kernel driver for Inspiron laptops, displays
902 the left fan status as listed in /proc/i8k (translated to human-
903 readable). Beware, some laptops i8k reports these fans in re‐
904 verse order.
905 i8k_right_fan_rpm
908 If running the i8k kernel driver for Inspiron laptops, displays
909 the right fan's rate of rotation, in revolutions per minute as
910 listed in /proc/i8k. Beware, some laptops i8k reports these fans
911 in reverse order.
912 i8k_right_fan_status
915 If running the i8k kernel driver for Inspiron laptops, displays
916 the right fan status as listed in /proc/i8k (translated to hu‐
917 man-readable). Beware, some laptops i8k reports these fans in
918 reverse order.
919 i8k_serial
922 If running the i8k kernel driver for Inspiron laptops, displays
923 your laptop serial number as listed in /proc/i8k.
924 i8k_version
927 If running the i8k kernel driver for Inspiron laptops, displays
928 the version formatting of /proc/i8k.
929 ibm_fan
932 If running the IBM ACPI, displays the fan speed.
933 ibm_temps N
936 If running the IBM ACPI, displays the temperatures from the IBM
937 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
938 GPU.
939 ibm_volume
942 If running the IBM ACPI, displays the "master" volume, con‐
943 trolled by the volume keys (0-14).
944 ibm_brightness
947 If running the IBM ACPI, displays the brigtness of the laptops's
948 LCD (0-7).
949 if_empty (var)
952 if conky variable VAR is empty, display everything between
953 $if_empty and the matching $endif
954 if_gw if there is at least one default gateway, display everything be‐
957 tween $if_gw and the matching $endif
958 if_running (process)
961 if PROCESS is running, display everything $if_running and the
962 matching $endif
963 if_existing file (string)
966 if FILE exists, display everything between if_existing and the
967 matching $endif. The optional second paramater checks for FILE
968 containing the specified string and prints everything between
969 $if_existing and the matching $endif.
970 if_mounted (mountpoint)
973 if MOUNTPOINT is mounted, display everything between $if_mounted
974 and the matching $endif
975 if_smapi_bat_installed (INDEX)
978 when using smapi, if the battery with index INDEX is installed,
979 display everything between $if_smapi_bat_installed and the
980 matching $endif
981 if_up (interface)
984 if INTERFACE exists and is up, display everything between $if_up
985 and the matching $endif
986 imap_messages (args)
989 Displays the number of messages in your global IMAP inbox by de‐
990 fault. You can define individual IMAP inboxes seperately by
991 passing arguments to this object. Arguments are: "host user pass
992 [-i interval] [-p port] [-e command]". Default port is 143, de‐
993 fault interval is 5 minutes. If the password is supplied as '*',
994 you will be prompted to enter the password when Conky starts.
995 imap_unseen (args)
998 Displays the number of unseen messages in your global IMAP inbox
999 by default. You can define individual IMAP inboxes seperately by
1000 passing arguments to this object. Arguments are: "host user pass
1001 [-i interval] [-p port] [-e command]". Default port is 143, de‐
1002 fault interval is 5 minutes. If the password is supplied as '*',
1003 you will be prompted to enter the password when Conky starts.
1004 ioscheduler disk
1007 Prints the current ioscheduler used for the given disk name
1008 (i.e. e.g. "hda" or "sdb")
1009 kernel Kernel version
1012 laptop_mode
1015 The value of /proc/sys/vm/laptop_mode
1016 loadavg
1019 (1,2,3)> System load average, 1 is for past 1 minute, 2 for past
1020 5 minutes and 3 for past 15 minutes.
1021 machine
1024 Machine, i686 for example
1025 mails (mailbox) (interval)
1028 Mail count in the specified mailbox or your mail spool if not.
1029 Both mbox and maildir type mailboxes are supported. You can use
1030 a program like fetchmail to get mails from some server using
1031 your favourite protocol. See also new_mails.
1032 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1035 width) mbox
1036 Print a summary of recent messages in an mbox format mailbox.
1037 mbox parameter is the filename of the mailbox (can be encapsu‐
1038 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1039 mem Amount of memory in use
1042 membar (height),(width)
1045 Bar that shows amount of memory in use
1046 memmax Total amount of memory
1049 memperc
1052 Percentage of memory in use
1053 mpd_artist
1056 Artist in current MPD song must be enabled at compile
1057 mpd_album
1060 Album in current MPD song
1061 mpd_bar (height),(width)
1064 Bar of mpd's progress
1065 mpd_bitrate
1068 Bitrate of current song
1069 mpd_status
1072 Playing, stopped, et cetera.
1073 mpd_title (max length)
1076 Title of current MPD song
1077 mpd_vol
1080 MPD's volume
1081 mpd_elapsed
1084 Song's elapsed time
1085 mpd_length
1088 Song's length
1089 mpd_percent
1092 Percent of song's progress
1093 mpd_random
1096 Random status (On/Off)
1097 mpd_repeat
1100 Repeat status (On/Off)
1101 mpd_track
1104 Prints the MPD track field
1105 mpd_name
1108 Prints the MPD name field
1109 mpd_file
1112 Prints the file name of the current MPD song
1113 mpd_smart
1116 Prints the song name in either the form "artist - title" or file
1117 name, depending on whats available
1118 nameserver (index)
1121 Print a nameserver from /etc/resolv.conf. Index starts at and
1122 defaults to 0.
1123 new_mails (mailbox) (interval)
1126 Unread mail count in the specified mailbox or mail spool if not.
1127 Both mbox and maildir type mailboxes are supported.
1128 nodename
1131 Hostname
1132 outlinecolor (color)
1135 Change outline color
1136 pb_battery item
1139 If running on Apple powerbook/ibook, display information on bat‐
1140 tery status. The item parameter specifies, what information to
1141 display. Exactly one item must be specified. Valid items are:
1142 status: Display if battery is fully charged, charging, discharg‐
1144 ing or absent (running on AC)
1145 percent: Display charge of battery in percent, if charging or
1146 discharging. Nothing will be displayed, if battery is fully
1147 charged or absent.
1148 time: Display the time remaining until the battery will be fully
1149 charged or discharged at current rate. Nothing is displayed, if
1150 battery is absent or if it's present but fully charged and not
1151 discharging.
1152 platform (dev) type n
1155 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
1156 omitted if you have only one platform device. Platform type is
1157 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
1158 (Celsius) or 'tempf' (Fahrenheit) meaning temperature. Parameter
1159 n is number of the sensor. See /sys/bus/platform/devices/ on
1160 your local computer.
1161 pop3_unseen (args)
1164 Displays the number of unseen messages in your global POP3 inbox
1165 by default. You can define individual POP3 inboxes seperately by
1166 passing arguments to this object. Arguments are: "host user pass
1167 [-i interval] [-p port] [-e command]". Default port is 110, de‐
1168 fault interval is 5 minutes. If the password is supplied as '*',
1169 you will be prompted to enter the password when Conky starts.
1170 pop3_used (args)
1173 Displays the amount of space (in MiB, 2^20) used in your global
1174 POP3 inbox by default. You can define individual POP3 inboxes
1175 seperately by passing arguments to this object. Arguments are:
1176 "host user pass [-i interval] [-p port] [-e command]". Default
1177 port is 110, default interval is 5 minutes. If the password is
1178 supplied as '*', you will be prompted to enter the password when
1179 Conky starts.
1180 pre_exec shell command
1183 Executes a shell command one time before conky displays anything
1184 and puts output as text.
1185 processes
1188 Total processes (sleeping and running)
1189 running_processes
1192 Running processes (not sleeping), requires Linux 2.6
1193 shadecolor (color)
1196 Change shading color
1197 smapi (ARGS)
1200 when using smapi, display contents of the /sys/devices/plat‐
1201 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN‐
1202 DEX) (FILENAME)' to display the corresponding files' content.
1203 This is a very raw method of accessing the smapi values. When
1204 available, better use one of the smapi_* variables instead.
1205 smapi_bat_perc (INDEX)
1208 when using smapi, display the remaining capacity in percent of
1209 the battery with index INDEX. This is a separate variable be‐
1210 cause it supports the 'use_spacer' configuration option.
1211 smapi_bat_bar (INDEX),(height),(width)
1214 when using smapi, display the remaining capacity of the battery
1215 with index INDEX as a bar.
1216 stippled_hr (space)
1219 Stippled (dashed) horizontal line
1220 swapbar (height),(width)
1223 Bar that shows amount of swap in use
1224 swap Amount of swap in use
1227 swapmax
1230 Total amount of swap
1231 swapperc
1234 Percentage of swap in use
1235 sysname
1238 System name, Linux for example
1239 tcp_portmon port_begin port_end item (index) (ip4 only at present)
1242 TCP port monitor for specified local ports. Port numbers must be
1243 in the range 1 to 65535. Valid items are:
1244 count - total number of connections in the range
1246 rip - remote ip address
1247 rhost - remote host name
1248 rport - remote port number
1249 rservice - remote service name from /etc/services
1250 lip - local ip address
1251 lhost - local host name
1252 lport - local port number
1253 lservice - local service name from /etc/services
1254 The connection index provides you with access to each connection
1256 in the port monitor. The monitor will return information for in‐
1257 dex values from 0 to n-1 connections. Values higher than n-1 are
1258 simply ignored. For the "count" item, the connection index must
1259 be omitted. It is required for all other items.
1260 Examples:
1262 ${tcp_portmon 6881 6999 count} - displays the number of connec‐
1263 tions in the bittorrent port range
1264 ${tcp_portmon 22 22 rip 0} - displays the remote host ip of the
1265 first sshd connection
1266 ${tcp_portmon 22 22 rip 9} - displays the remote host ip of the
1267 tenth sshd connection
1268 ${tcp_portmon 1 1024 rhost 0} - displays the remote host name of
1269 the first connection on a privileged port
1270 ${tcp_portmon 1 1024 rport 4} - displays the remote host port of
1271 the fifth connection on a privileged port
1272 ${tcp_portmon 1 65535 lservice 14} - displays the local service
1273 name of the fifteenth connection in the range of all ports
1274 Note that port monitor variables which share the same port range
1276 actually refer to the same monitor, so many references to a sin‐
1277 gle port range for different items and different indexes all use
1278 the same monitor internally. In other words, the program avoids
1279 creating redundant monitors.
1280 texeci interval command
1282 Runs a command at an interval inside a thread and displays the
1283 output. Same as $execi, except the command is run inside a
1284 thread. Use this if you have a slow script to keep Conky updat‐
1285 ing. You should make the interval slightly longer then the time
1286 it takes your script to execute. For example, if you have a
1287 script that take 5 seconds to execute, you should make the in‐
1288 terval at least 6 seconds. See also $execi.
1289 offset (pixels)
1292 Move text over by N pixels. See also $voffset.
1293 rss url delay_in_minutes action item_num
1296 Download and parse RSS feeds. Action may be one of the follow‐
1297 ing: feed_title, item_title (with num par), item_desc (with num
1298 par) and item_titles.
1299 tab (width, (start))
1302 Puts a tab of the specified width, starting from column 'start'.
1303 tail logfile lines (interval)
1306 Displays last N lines of supplied text text file. If interval is
1307 not supplied, Conky assumes 2x Conky's interval. Max of 30 lines
1308 can be displayed, or until the text buffer is filled.
1309 time (format)
1312 Local time, see man strftime to get more information about for‐
1313 mat
1314 utime (format)
1317 Display time in UTC (universal coordinate time).
1318 tztime (timezone) (format)
1321 Local time for specified timezone, see man strftime to get more
1322 information about format. The timezone argument is specified in
1323 similar fashion as TZ environment variable. For hints, look in
1324 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
1325 totaldown net
1328 Total download, overflows at 4 GB on Linux with 32-bit arch and
1329 there doesn't seem to be a way to know how many times it has al‐
1330 ready done that before conky has started.
1331 top type, num
1334 This takes arguments in the form:top (name) (number) Basically,
1335 processes are ranked from highest to lowest in terms of cpu us‐
1336 age, which is what (num) represents. The types are: "name",
1337 "pid", "cpu", "mem", "mem_res", "mem_vsize", and "time". There
1338 can be a max of 10 processes listed.
1339 top_mem type, num
1342 Same as top, except sorted by mem usage instead of cpu
1343 totalup net
1346 Total upload, this one too, may overflow
1347 updates Number of updates
1350 for debugging
1351 upspeed net
1354 Upload speed in kilobytes
1355 upspeedf net
1358 Upload speed in kilobytes with one decimal
1359 upspeedgraph net (height),(width) (gradient colour 1) (gradient colour
1362 2) (scale)
1363 Upload speed graph, colours defined in hex, minus the #. If
1364 scale is non-zero, it becomes the scale for the graph.
1365 uptime Uptime
1368 uptime_short
1371 Uptime in a shorter format
1372 user_number
1375 Number of users logged in
1376 user_names
1379 Lists the names of the users logged in
1380 user_terms
1383 Lists the consoles in use
1384 user_times
1387 Lists how long users have been logged in for
1388 voffset (pixels)
1391 Change vertical offset by N pixels. Negative values will cause
1392 text to overlap. See also $offset.
1393 voltage_mv (n)
1396 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
1397 omitted, the parameter defaults to 1.
1398 voltage_v (n)
1401 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit‐
1402 ted, the parameter defaults to 1.
1403 wireless_essid net
1406 Wireless access point ESSID (Linux only)
1407 wireless_mode net
1410 Wireless mode (Managed/Ad-Hoc/Master) (Linux only)
1411 wireless_bitrate net
1414 Wireless bitrate (ie 11 Mb/s) (Linux only)
1415 wireless_ap net
1418 Wireless access point MAC address (Linux only)
1419 wireless_link_qual net
1422 Wireless link quality (Linux only)
1423 wireless_link_qual_max net
1426 Wireless link quality maximum value (Linux only)
1427 wireless_link_qual_perc net
1430 Wireless link quality in percents (Linux only)
1431 wireless_link_bar (height), (width) net
1434 Wireless link quality bar (Linux only)
1435 xmms2_artist
1438 Artist in current XMMS2 song
1439 xmms2_album
1442 Album in current XMMS2 song
1443 xmms2_title
1446 Title in current XMMS2 song
1447 xmms2_genre
1450 Genre in current XMMS2 song
1451 xmms2_comment
1454 Comment in current XMMS2 song
1455 xmms2_decoder
1458 Decoder plugin used
1459 xmms2_transport
1462 Transport plugin used
1463 xmms2_url
1466 Full path to current song
1467 xmms2_tracknr
1470 Track number in current XMMS2 song
1471 xmms2_bitrate
1474 Bitrate of current song
1475 xmms2_id
1478 XMMS2 id of current song
1479 xmms2_duration
1482 Duration of current song
1483 xmms2_elapsed
1486 Song's elapsed time
1487 xmms2_size
1490 Size of current song
1491 xmms2_percent
1494 Percent of song's progress
1495 xmms2_status
1498 XMMS2 status (Playing, Paused, Stopped, or Disconnected)
1499 xmms2_bar (height),(width)
1502 Bar of XMMS2's progress
1503 xmms2_smart
1506 Prints the song name in either the form "artist - title" or file
1507 name, depending on whats available
1508
1511 conky -t '${time %D %H:%M}' -o -u 30
1512 Start Conky in its own window with date and clock as text and 30
1513 sec update interval.
1514 conky -a top_left -x 5 -y 500 -d
1516 Start Conky to background at coordinates (5, 500).
1517
1519 ~/.conkyrc default configuration file
1520
1522 Drawing to root or some other desktop window directly doesn't work with
1523 all window managers. Especially doesn't work well with Gnome and it has
1524 been reported that it doesn't work with KDE either. Nautilus can be
1525 disabled from drawing to desktop with program gconf-editor. Uncheck
1526 show_desktop in /apps/nautilus/preferences/. There is -w switch in
1527 Conky to set some specific window id. You might find xwininfo -tree
1528 useful to find the window to draw to. You can also use -o argument
1529 which makes Conky to create its own window. If you do try running Conky
1530 in its own window, be sure to read up on the own_window_type settings
1531 and experiment.
1532
1534 ⟨http://conky.sourceforge.net/⟩
1535 ⟨http://www.sourceforge.net/projects/conky⟩
1537 #conky on irc.freenode.net
1539
1541 Copyright (c) 2005-2008 Brenden Matthews, Philip Kovacs, et. al. Any
1542 original torsmo code is licensed under the BSD license (see LICENSE.BSD
1543 for a copy). All code written since the fork of torsmo is licensed un‐
1544 der the GPL (see LICENSE.GPL for a copy), except where noted different‐
1545 ly (such as in portmon code, timed thread code, and audacious code
1546 which are LGPL, and prss which is an MIT-style license).
1547
1549 The Conky dev team (see AUTHORS for a full list of contributors).
1550 2008-03-31 conky(1)