1 Conky (http://conky.rty.ca)
5 Conky is a system monitor for X originally based on the torsmo code.
6 Since it's original conception, Conky has changed a fair bit from
7 it's predecessor. Conky can display just about anything, either on
8 your root desktop or in it's own window. Conky has many built-in
9 objects, as well as the ability to execute programs and scripts,
10 then display the output from stdout.
12 We are always looking for help, and anyone interested in becoming
13 a developer is welcome. Please use the facilities at SourceForge
14 to make bug reports, feature requests, and submit patches.
16 Thanks for your interest in Conky.
18 THINGS YOU SHOULD KNOW
20 Conky is generally very good on resources. However, certain objects in
21 Conky are harder on resources then others. In particular, the $tail,
22 $top, $font, and $graph objects are quite costly in comparison to
25 If you do use them, please do not complain about memory or CPU usage,
26 unless you think something is going seriously wrong (mem leak, et cetera).
30 To compile and run Conky with all optional components (If you run Gentoo, see the "Ebuild" Section below):
32 ./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-metar --enable-seti
36 Conky doesn't probably compile with other compilers than gcc and icc. It
37 doesn't compile with C89 compiler and not even with pure C99. It uses few
38 things that might not exist: strdup(), strcasecmp(), strncasecmp(), optarg
39 variable with getopt() and long long (not in C89). Crashes in file system
40 statistics stuff when compiled with icc, I don't know exactly why.
42 You can disable 'drawing to own window' feature in case you don't need it
43 by passing --disable-own-window to configure -script.
47 Conky is in Gentoo's Portage. Simply use "emerge conky" to install conky.
48 There is also usually an up-to-date ebuild within Conky's package or in
53 Default configuration file is $HOME/.conkyrc (can be changed from
54 conky.c among other things). See conkyrc.sample. You might want to copy
55 it to $HOME/.conkyrc and then start modifying it.
57 Configuration file confs
60 alignment Aligned position on screen, may be top_left,
61 top_right, bottom_left, bottom_right
62 background Boolean value, if true, Conky will be forked to
63 background when started
64 on_bottom Set conky on the bottom of all other applications
65 border_margin Border margin in pixels
66 border_width Border width in pixels
67 cpu_avg_samples The number of samples to average for CPU monitoring
68 default_color Default color and border color
69 default_shade_color Default shading color and border's shading color
70 default_outline_color Default outline color
71 Use the Xdbe extension? (eliminates flicker) It is
72 double_buffer highly recommended to use own window with this one
73 so double buffer won't be so big.
74 draw_borders Draw borders around text?
75 draw_shades Draw shades?
76 draw_outline Draw outlines?
77 font Font name in X, xfontsel can be used to get a nice font
78 gap_x Gap between right or left border of screen, same as passing -x at command line
79 gap_y Gap between top or bottom border of screen, same as passing -y at command line
80 no_buffers Substract (file system) buffers from used memory?
81 mail_spool Mail spool for mail checking
82 metar_station METAR station code for weather, see http://www.wrh.noaa.gov/ if you need to find your code.
83 metar_server Define a custom METAR ftp server
84 metar_path Path on server to use
85 minimum_size Minimum size of window
86 mldonkey_hostname Hostname for mldonkey stuff, defaults to localhost
87 mldonkey_port Mldonkey port, 4001 default
88 mldonkey_login Mldonkey login, default none
89 mldonkey_password Mldonkey password, default none
90 mpd_host Host of MPD server
91 mpd_post Port of MPD server
92 mpd_password MPD server password
93 net_avg_samples The number of samples to average for net data
94 override_utf8_locale Force UTF8? requires XFT
95 own_window Boolean, create own window to draw?
96 pad_percents Pad percentages to this many decimals (0 = no
98 stippled_borders Border stippling (dashing) in pixels
99 total_run_times Total number of times for Conky to update before
100 quitting. Zero makes Conky run forever
101 update_interval Update interval in seconds
102 uppercase Boolean value, if true, text is rendered in upper
104 use_spacer Adds spaces after certain objects to stop them
105 from moving other things around. Note that
106 this only helps if you are using a mono font,
107 such as Bitstream Vera Sans Mono.
108 use_xft Use Xft (anti-aliased font and stuff)
109 text After this begins text to be formatted on screen
111 Boolean variable without value in text means yes. Value may be also yes,
112 true or any negative or positive integer meaning yes. No, false or zero
114 There may be some variables in text. Variable is given either in format
115 $variable or in ${variable}. Latter allows characters right after the
116 variable and must be used in some stuff because of arguments.
121 -V Prints version and exits
122 -a ALIGNMENT Text alignment on screen, {top,bottom}_{left,right}
123 -b Use double buffering (eliminates flicker)
124 -c FILE Config file to load instead of $HOME/.conkyrc
125 -d Daemonize, fork to background
127 -h Prints command line help and exits
128 -o Create own window to draw
129 -t TEXT Text to render, remember single quotes, like -t '$uptime'
130 -u SECS Update interval
131 -w WIN_ID Window id to draw
135 Command line options override configurations defined in configuration
140 Variable Arguments Description
142 addr (interface) IP address for an interface
143 acpiacadapter ACPI ac adapter state.
144 acpifan ACPI fan state
145 acpitemp ACPI temperature.
146 adt746xcpu CPU temperature from therm_adt746x
147 adt746xfan Fan speed from therm_adt746x
148 alignr (num) Right-justify text, with space of N
149 alignc Align text to centre
150 battery (num) Remaining capasity in ACPI or APM
151 battery. ACPI battery number can be
152 given as argument (default is BAT0).
153 buffers Amount of memory buffered
154 cached Amount of memory cached
155 color (color) Change drawing color to color
156 cpu CPU usage in percents
157 cpubar (height) Bar that shows CPU usage, height is
158 bar's height in pixels
159 cpugraph (height),(width) (gradient colour 1) (gradient colour 2)
160 CPU usage graph, with optional colours in hex,
162 downspeed net Download speed in kilobytes
163 downspeedf net Download speed in kilobytes with one
165 downspeedgraph net (height),(width) (gradient colour 1) (gradient colour 2)
166 Download speed graph, colours defined in
168 exec shell command Executes a shell command and displays
169 the output in conky. warning: this
170 takes a lot more resources than other
171 variables. I'd recommend coding wanted
172 behaviour in C and posting a patch :-).
173 execbar shell command Same as exec, except if the first value
174 return is a value between 0-100, it
175 will use that number for a bar.
176 The size for the bar is currently fixed,
177 but that may change in the future.
178 execgraph shell command Same as execbar, but graphs values
179 execi interval, shell command
180 Same as exec but with specific interval.
181 Interval can't be less than
182 update_interval in configuration.
183 font font Specify a different font. Only applies
185 fs_bar (height), (fs)Bar that shows how much space is used on
186 a file system. height is the height in
187 pixels. fs is any file on that file
189 fs_free (fs) Free space on a file system available
191 fs_free_perc (fs) Free percentage of space on a file
192 system available for users.
193 fs_size (fs) File system size
194 fs_used (fs) File system used space
195 hr (height) Horizontal line, height is the height in
197 i2c (dev), type, n I2C sensor from sysfs (Linux 2.6). dev
198 may be omitted if you have only one I2C
199 device. type is either in (or vol)
200 meaning voltage, fan meaning fan or
201 temp/tempf (first in C, second in F)
202 meaning temperature. n is number of the
203 sensor. See /sys/bus/i2c/devices/ on
205 if_running (process) if PROCESS is running, display
206 everything if_running and the matching $endif
207 if_existing (file) if FILE exists, display everything between
208 if_existing and the matching $endif
209 if_mounted (mountpoint) if MOUNTPOINT is mounted, display everything between
210 if_mounted and the matching $endif
211 else Text to show if any of the above are not true
212 kernel Kernel version
213 linkstatus (interface) Get the link status for wireless connections
214 loadavg (1), (2), (3) System load average, 1 is for past 1
215 minute, 2 for past 5 minutes and 3 for
217 machine Machine, i686 for example
218 mails Mail count in mail spool. You can use
219 program like fetchmail to get mails from
220 some server using your favourite
221 protocol. See also new_mails.
222 mem Amount of memory in use
223 membar (height) Bar that shows amount of memory in use
224 memmax Total amount of memory
225 memperc Percentage of memory in use
229 metar_tempf Temp in F
231 metar_dew_point There are a bunch of these
232 metar_rh and they are self-explanatory
233 metar_windspeed Windspeed units are in knots
239 ml_upload_counter total session upload in mb
240 ml_download_counter total session download in mb
241 ml_nshared_files number of shared files
242 ml_shared_counter total session shared in mb, buggy
243 in some mldonkey versions
244 ml_tcp_upload_rate tcp upload rate in kb/s
245 ml_tcp_download_rate tcp download rate in kb/s
246 ml_udp_upload_rate udp upload rate in kb/s
247 ml_udp_download_rate udp download rate in kb/s
248 ml_ndownloaded_files number of completed files
249 ml_ndownloading_files number of downloading files
251 mpd_artist Artist in current MPD song
252 (must be enabled at compile)
253 mpd_album Album in current MPD song
254 mpd_bar (height) Bar of mpd's progress
255 mpd_bitrate Bitrate of current song
256 mpd_status Playing, stopped, et cetera.
257 mpd_title Title of current MPD song
259 mpd_elapsed Song's elapsed time
260 mpd_length Song's length
261 mpd_percent Percent of song's progress
262 new_mails Unread mail count in mail spool.
264 outlinecolor (color) Change outline color
265 pre_exec shell command Executes a shell command one time before
266 conky displays anything and puts output
268 processes Total processes (sleeping and running)
269 running_processes Running processes (not sleeping),
271 shadecolor (color) Change shading color
272 stippled_hr (space), Stippled (dashed) horizontal line
274 swapbar (height) Bar that shows amount of swap in use
275 swap Amount of swap in use
276 swapmax Total amount of swap
277 swapperc Percentage of swap in use
278 sysname System name, Linux for example
279 offset pixels Move text over by N pixels
280 tail logfile, lines (interval)
281 Displays last N lines of supplied text
282 text file. If interval is not supplied,
283 Conky assumes 2x Conky's interval.
285 Max of 30 lines can be displayed.
286 time (format) Local time, see man strftime to get more
287 information about format
288 totaldown net Total download, overflows at 4 GB on
289 Linux with 32-bit arch and there doesn't
290 seem to be a way to know how many times
291 it has already done that before conky
293 top type, num This takes arguments in the form:
295 Basically, processes are ranked from
296 highest to lowest in terms of cpu
297 usage, which is what <num> represents.
298 The types are: "name", "pid", "cpu", and
300 There can be a max of 10 processes listed.
301 top_mem type, num Same as top, except sorted by mem usage
303 totalup net Total upload, this one too, may overflow
304 updates Number of updates (for debugging)
305 upspeed net Upload speed in kilobytes
306 upspeedf net Upload speed in kilobytes with one
308 upspeedgraph net (height),(width) (gradient colour 1) (gradient colour 2)
309 Upload speed graph, colours defined in
312 uptime_short Uptime in a shorter format
314 seti_prog Seti@home current progress
315 seti_progbar (height) Seti@home current progress bar
316 seti_credit Seti@hoome total user credit
319 colors are parsed using XParsecolor(), there might be a list of them:
320 /usr/X11R6/lib/X11/rgb.txt. color can be also in #rrggbb format (hex).
322 Note that when displaying bytes, power is 1024 and not 1000 so 1M really
323 means 1024*1024 bytes and not 1000*1000.
327 Drawing to root or some other desktop window directly doesn't work with
328 all window managers. Especially doesn't work well with Gnome and it has
329 been reported that it doesn't work with KDE either. Nautilus can be
330 disabled from drawing to desktop with program gconf-editor. Uncheck
331 show_desktop in /apps/nautilus/preferences/. There is -w switch in Conky
332 to set some specific window id. You might find xwininfo -tree useful to
333 find the window to draw to. You can also use -o argument which makes
334 Conky to create its own window.
projects / monky / blob