1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
|
.\" This file was automatically generated from x11vnc -help output.
.TH X11VNC "1" "February 2005" "x11vnc " "User Commands"
.SH NAME
x11vnc - allow VNC connections to real X11 displays
version: 0.7.1, lastmod: 2005-02-23
.SH SYNOPSIS
.B x11vnc
[OPTION]...
.SH DESCRIPTION
.PP
Typical usage is:
.IP
Run this command in a shell on the remote machine "far-host"
with X session you wish to view:
.IP
x11vnc -display :0
.IP
Then run this in another window on the machine you are sitting at:
.IP
vncviewer far-host:0
.PP
Once x11vnc establishes connections with the X11 server and starts listening
as a VNC server it will print out a string: PORT=XXXX where XXXX is typically
5900 (the default VNC server port). One would next run something like
this on the local machine: "vncviewer hostname:N" where "hostname" is
the name of the machine running x11vnc and N is XXXX - 5900, i.e. usually
"vncviewer hostname:0".
.PP
By default x11vnc will not allow the screen to be shared and it will exit
as soon as the client disconnects. See \fB-shared\fR and \fB-forever\fR below to override
these protections. See the FAQ on how to tunnel the VNC connection through
an encrypted channel such as
.IR ssh (1).
.PP
For additional info see: http://www.karlrunge.com/x11vnc/
and http://www.karlrunge.com/x11vnc/#faq
.PP
Rudimentary config file support: if the file $HOME/.x11vncrc exists then each
line in it is treated as a single command line option. Disable with \fB-norc.\fR
For each option name, the leading character "-" is not required. E.g. a
line that is either "forever" or "\fB-forever\fR" may be used and are equivalent.
Likewise "wait 100" or "\fB-wait\fR \fI100\fR" are acceptable and equivalent lines.
The "#" character comments out to the end of the line in the usual way.
Leading and trailing whitespace is trimmed off. Lines may be continued with
a "\\" as the last character of a line (it becomes a space character).
.PP
.SH OPTIONS
.PP
\fB-display\fR \fIdisp\fR
.IP
X11 server display to connect to, usually :0. The X
server process must be running on same machine and
support MIT-SHM. Equivalent to setting the DISPLAY
environment variable to \fIdisp\fR.
.PP
\fB-auth\fR \fIfile\fR
.IP
Set the X authority file to be \fIfile\fR, equivalent to
setting the XAUTHORITY environment variable to \fIfile\fR
before startup. Same as \fB-xauth\fR file. See
.IR Xsecurity (7)
,
.IR xauth (1)
man pages for more info.
.PP
\fB-id\fR \fIwindowid\fR
.IP
Show the window corresponding to \fIwindowid\fR not
the entire display. New windows like popup menus,
transient toplevels, etc, may not be seen or may be
clipped. Disabling SaveUnders or BackingStore in the
X server may help show them. x11vnc may crash if the
window is initially partially obscured, changes size,
is iconified, etc. Some steps are taken to avoid this
and the \fB-xrandr\fR mechanism is used to track resizes. Use
.IR xwininfo (1)
to get the window id, or use "\fB-id\fR \fIpick\fR"
to have x11vnc run
.IR xwininfo (1)
for you and extract
the id. The \fB-id\fR option is useful for exporting very
simple applications (e.g. the current view on a webcam).
.PP
\fB-sid\fR \fIwindowid\fR
.IP
As \fB-id,\fR but instead of using the window directly it
shifts a root view to it: this shows SaveUnders menus,
etc, although they will be clipped if they extend beyond
the window.
.PP
\fB-flashcmap\fR
.IP
In 8bpp indexed color, let the installed colormap flash
as the pointer moves from window to window (slow).
.PP
\fB-notruecolor\fR
.IP
For 8bpp displays, force indexed color (i.e. a colormap)
even if it looks like 8bpp TrueColor (rare problem).
.PP
\fB-visual\fR \fIn\fR
.IP
Experimental option: probably does not do what you
think. It simply *forces* the visual used for the
framebuffer; this may be a bad thing... (e.g. messes
up colors or cause a crash). It is useful for testing
and for some workarounds. n may be a decimal number,
or 0x hex. Run
.IR xdpyinfo (1)
for the values. One may
also use "TrueColor", etc. see <X11/X.h> for a list.
If the string ends in ":m" the for better or for
worse the visual depth is forced to be m.
.PP
\fB-overlay\fR
.IP
Handle multiple depth visuals on one screen, e.g. 8+24
and 24+8 overlay visuals (the 32 bits per pixel are
packed with 8 for PseudoColor and 24 for TrueColor).
.IP
Currently \fB-overlay\fR only works on Solaris via
.IR XReadScreen (3X11)
and IRIX using
.IR XReadDisplay (3).
On Solaris there is a problem with image "bleeding"
around transient popup menus (but not for the menu
itself): a workaround is to disable SaveUnders
by passing the "\fB-su\fR" argument to Xsun (in
/etc/dt/config/Xservers). Also note that the mouse
cursor shape is exactly correct in this mode.
.IP
Use \fB-overlay\fR as a workaround for situations like these:
Some legacy applications require the default visual to
be 8bpp (8+24), or they will use 8bpp PseudoColor even
when the default visual is depth 24 TrueColor (24+8).
In these cases colors in some windows will be messed
up in x11vnc unless \fB-overlay\fR is used. Another use of
\fB-overlay\fR is to enable showing the exact mouse cursor
shape (details below).
.IP
Under \fB-overlay,\fR performance will be somewhat degraded
due to the extra image transformations required.
For optimal performance do not use \fB-overlay,\fR but rather
configure the X server so that the default visual is
depth 24 TrueColor and try to have all apps use that
visual (e.g. some apps have \fB-use24\fR or \fB-visual\fR options).
.PP
\fB-overlay_nocursor\fR
.IP
Sets \fB-overlay,\fR but does not try to draw the exact mouse
cursor shape using the overlay mechanism.
.PP
\fB-scale\fR \fIfraction\fR
.IP
Scale the framebuffer by factor \fIfraction\fR. Values
less than 1 shrink the fb, larger ones expand it.
Note: image may not be sharp and response may be
slower. Currently the cursor shape is not scaled.
If \fIfraction\fR contains a decimal point "." it
is taken as a floating point number, alternatively
the notation "m/n" may be used to denote fractions
exactly, e.g. \fB-scale\fR 2/3.
.IP
Scaling Options: can be added after \fIfraction\fR via
":", to supply multiple ":" options use commas.
If you just want a quick, rough scaling without
blending, append ":nb" to \fIfraction\fR (e.g. \fB-scale\fR
1/3:nb). For compatibility with vncviewers the scaled
width is adjusted to be a multiple of 4: to disable
this use ":n4". More esoteric options: ":in" use
interpolation scheme even when shrinking, ":pad",
pad scaled width and height to be multiples of scaling
denominator (e.g. 3 for 2/3).
.PP
\fB-viewonly\fR
.IP
All VNC clients can only watch (default off).
.PP
\fB-shared\fR
.IP
VNC display is shared (default off).
.PP
\fB-once\fR
.IP
Exit after the first successfully connected viewer
disconnects, opposite of \fB-forever.\fR This is the Default.
.PP
\fB-forever\fR
.IP
Keep listening for more connections rather than exiting
as soon as the first client(s) disconnect. Same as \fB-many\fR
.PP
\fB-timeout\fR \fIn\fR
.IP
Exit unless a client connects within the first n seconds
of startup.
.PP
\fB-inetd\fR
.IP
Launched by
.IR inetd (1):
stdio instead of listening socket.
Note: if you are not redirecting stderr to a log file
(via shell 2> or \fB-o\fR option) you must also specify the
\fB-q\fR option, otherwise the stderr goes to the viewer.
.PP
\fB-connect\fR \fIstring\fR
.IP
For use with "vncviewer -listen" reverse connections.
If \fIstring\fR has the form "host" or "host:port"
the connection is made once at startup. Use commas
for a list of host's and host:port's.
.IP
If \fIstring\fR contains "/" it is instead interpreted
as a file to periodically check for new hosts.
The first line is read and then the file is truncated.
Be careful for this usage mode if x11vnc is running as
root (e.g. via
.IR inetd (1)
or
.IR gdm (1)
).
.PP
\fB-vncconnect,\fR \fB-novncconnect\fR
.IP
Monitor the VNC_CONNECT X property set by the standard
VNC program
.IR vncconnect (1).
When the property is
set to "host" or "host:port" establish a reverse
connection. Using
.IR xprop (1)
instead of vncconnect may
work (see the FAQ). Default: \fB-vncconnect\fR
.PP
\fB-allow\fR \fIhost1[,host2..]\fR
.IP
Only allow client connections from hosts matching
the comma separated list of hostnames or IP addresses.
Can also be a numerical IP prefix, e.g. "192.168.100."
to match a simple subnet, for more control build
libvncserver with libwrap support (See the FAQ). If the
list contains a "/" it instead is a interpreted as a
file containing addresses or prefixes that is re-read
each time a new client connects. Lines can be commented
out with the "#" character in the usual way.
.PP
\fB-localhost\fR
.IP
Same as \fB-allow\fR 127.0.0.1
.PP
\fB-input\fR \fIstring\fR
.IP
Fine tuning of allowed user input. If \fIstring\fR does
not contain a comma "," the tuning applies only to
normal clients. Otherwise the part before "," is
for normal clients and the part after for view-only
clients. "K" is for Keystroke input, "M" for
Mouse-motion input, and "B" for Button-click input.
Their presence in the string enables that type of input.
E.g. "\fB-input\fR \fIM\fR" means normal users can only move
the mouse and "\fB-input\fR \fIKMB,M\fR" lets normal users do
anything and enables view-only users to move the mouse.
This option is ignored when a global \fB-viewonly\fR is in
effect (all input is discarded).
.PP
\fB-viewpasswd\fR \fIstring\fR
.IP
Supply a 2nd password for view-only logins. The \fB-passwd\fR
(full-access) password must also be supplied.
.PP
\fB-passwdfile\fR \fIfilename\fR
.IP
Specify libvncserver \fB-passwd\fR via the first line of the
file \fIfilename\fR instead of via command line (where
others might see it via
.IR ps (1)
). If a second non blank
line exists in the file it is taken as a view-only
password (i.e. \fB-viewpasswd)\fR To supply an empty password
for either field the string "__EMPTY__" may be used.
Note: \fB-passwdfile\fR is a simple plaintext passwd, see
also \fB-rfbauth\fR and \fB-storepasswd\fR below for obfuscated
VNC password files. Neither file should be readable
by others.
.PP
\fB-storepasswd\fR \fIpass\fR \fIfile\fR
.IP
Store password \fIpass\fR as the VNC password in the
file \fIfile\fR. Once the password is stored the
program exits. Use the password via "\fB-rfbauth\fR \fIfile\fR"
.PP
\fB-accept\fR \fIstring\fR
.IP
Run a command (possibly to prompt the user at the
X11 display) to decide whether an incoming client
should be allowed to connect or not. \fIstring\fR is
an external command run via
.IR system (3)
or some special
cases described below. Be sure to quote \fIstring\fR
if it contains spaces, shell characters, etc. If the
external command returns 0 the client is accepted,
otherwise the client is rejected. See below for an
extension to accept a client view-only.
.IP
If x11vnc is running as root (say from
.IR inetd (1)
or from
display managers
.IR xdm (1)
,
.IR gdm (1)
, etc), think about the
security implications carefully before supplying this
option (likewise for the \fB-gone\fR option).
.IP
Environment: The RFB_CLIENT_IP environment variable will
be set to the incoming client IP number and the port
in RFB_CLIENT_PORT (or -1 if unavailable). Similarly,
RFB_SERVER_IP and RFB_SERVER_PORT (the x11vnc side
of the connection), are set to allow identification
of the tcp virtual circuit. The x11vnc process
id will be in RFB_X11VNC_PID, a client id number in
RFB_CLIENT_ID, and the number of other connected clients
in RFB_CLIENT_COUNT. RFB_MODE will be "accept"
.IP
If \fIstring\fR is "popup" then a builtin popup window
is used. The popup will time out after 120 seconds,
use "popup:N" to modify the timeout to N seconds
(use 0 for no timeout)
.IP
If \fIstring\fR is "xmessage" then an
.IR xmessage (1)
invocation is used for the command. xmessage must be
installed on the machine for this to work.
.IP
Both "popup" and "xmessage" will present an option
for accepting the client "View-Only" (the client
can only watch). This option will not be presented if
\fB-viewonly\fR has been specified, in which case the entire
display is view only.
.IP
If the user supplied command is prefixed with something
like "yes:0,no:*,view:3 mycommand ..." then this
associates the numerical command return code with
the actions: accept, reject, and accept-view-only,
respectively. Use "*" instead of a number to indicate
the default action (in case the command returns an
unexpected value). E.g. "no:*" is a good choice.
.IP
Note that x11vnc blocks while the external command
or popup is running (other clients may see no updates
during this period).
.IP
More \fB-accept\fR tricks: use "popupmouse" to only allow
mouse clicks in the builtin popup to be recognized.
Similarly use "popupkey" to only recognize
keystroke responses. These are to help avoid the
user accidentally accepting a client by typing or
clicking. All 3 of the popup keywords can be followed
by +N+M to supply a position for the popup window.
The default is to center the popup window.
.PP
\fB-gone\fR \fIstring\fR
.IP
As \fB-accept,\fR except to run a user supplied command when
a client goes away (disconnects). RFB_MODE will be
set to "gone" and the other RFB_* variables are as
in \fB-accept.\fR Unlike \fB-accept,\fR the command return code
is not interpreted by x11vnc. Example: \fB-gone\fR 'xlock &'
.PP
\fB-users\fR \fIlist\fR
.IP
If x11vnc is started as root (say from
.IR inetd (1)
or from
display managers
.IR xdm (1)
,
.IR gdm (1)
, etc), then as soon
as possible after connections to the X display are
established try to switch to one of the users in the
comma separated \fIlist\fR. If x11vnc is not running as
root this option is ignored.
.IP
Why use this option? In general it is not needed since
x11vnc is already connected to the X display and can
perform its primary functions. The option was added
to make some of the *external* utility commands x11vnc
occasionally runs work properly. In particular under
GNOME and KDE to implement the "\fB-solid\fR \fIcolor\fR" feature
external commands (gconftool-2 and dcop) must be run
as the user owning the desktop session. Since this
option switches userid it also affects the userid used
to run the processes for the \fB-accept\fR and \fB-gone\fR options.
It also affects the ability to read files for options
such as \fB-connect,\fR \fB-allow,\fR and \fB-remap.\fR Note that the
\fB-connect\fR file is also sometimes written to.
.IP
So be careful with this option since in many situations
its use can decrease security.
.IP
The switch to a user will only take place if the
display can still be successfully opened as that user
(this is primarily to try to guess the actual owner
of the session). Example: "\fB-users\fR \fIfred,wilma,betty\fR".
Note that a malicious user "barney" by quickly using
"xhost +" when logging in may get x11vnc to switch
to user "fred". What happens next?
.IP
Under display managers it may be a long time before
the switch succeeds (i.e. a user logs in). To make
it switch immediately regardless if the display
can be reopened prefix the username with the "+"
character. E.g. "\fB-users\fR \fI+bob\fR" or "\fB-users\fR \fI+nobody\fR".
The latter (i.e. switching immediately to user
"nobody") is probably the only use of this option
that increases security.
.IP
To immediately switch to a user *before* connections
to the X display are made or any files opened use the
"=" character: "\fB-users\fR \fI=bob\fR". That user needs to
be able to open the X display of course.
.IP
The special user "guess=" means to examine the utmpx
database (see
.IR who (1)
) looking for a user attached to
the display number (from DISPLAY or \fB-display\fR option)
and try him/her. To limit the list of guesses, use:
"\fB-users\fR \fIguess=bob,betty\fR".
.IP
Even more sinister is the special user "lurk=" that
means to try to guess the DISPLAY from the utmpx login
database as well. So it "lurks" waiting for anyone
to log into an X session and then connects to it.
Specify a list of users after the = to limit which
users will be tried. To enable a difference searching
mode, if the first user in the list is something like
":0" or ":0-2" that indicates a range of DISPLAY
numbers that will be tried (regardless of whether
they are in the utmpx database) for all users that
are logged in. Examples: "\fB-users\fR \fIlurk=\fR" and also
"\fB-users\fR \fIlurk=:0-1,bob,mary\fR"
.IP
Be especially careful using the "guess=" and "lurk="
modes. They are not recommended for use on machines
with untrustworthy local users.
.PP
\fB-noshm\fR
.IP
Do not use the MIT-SHM extension for the polling.
Remote displays can be polled this way: be careful this
can use large amounts of network bandwidth. This is
also of use if the local machine has a limited number
of shm segments and \fB-onetile\fR is not sufficient.
.PP
\fB-flipbyteorder\fR
.IP
Sometimes needed if remotely polled host has different
endianness. Ignored unless \fB-noshm\fR is set.
.PP
\fB-onetile\fR
.IP
Do not use the new copy_tiles() framebuffer mechanism,
just use 1 shm tile for polling. Limits shm segments
used to 3.
.PP
\fB-solid\fR \fI[color]\fR
.IP
To improve performance, when VNC clients are connected
try to change the desktop background to a solid color.
The [color] is optional: the default color is "cyan4".
For a different one specify the X color (rgb.txt name,
e.g. "darkblue" or numerical "#RRGGBB").
.IP
Currently this option only works on GNOME, KDE, CDE,
and classic X (i.e. with the background image on the
root window). The "gconftool-2" and "dcop" external
commands are run for GNOME and KDE respectively.
Other desktops won't work, e.g. Xfce (send us the
corresponding commands if you find them). If x11vnc is
running as root (
.IR inetd (1)
or
.IR gdm (1)
), the \fB-users\fR option
may be needed for GNOME and KDE. If x11vnc guesses
your desktop incorrectly, you can force it by prefixing
color with "gnome:", "kde:", "cde:" or "root:".
.PP
\fB-blackout\fR \fIstring\fR
.IP
Black out rectangles on the screen. \fIstring\fR is a
comma separated list of WxH+X+Y type geometries for
each rectangle.
.PP
\fB-xinerama\fR
.IP
If your screen is composed of multiple monitors
glued together via XINERAMA, and that screen is
non-rectangular this option will try to guess the
areas to black out (if your system has libXinerama).
.IP
In general on XINERAMA displays you may need to use the
\fB-xwarppointer\fR option if the mouse pointer misbehaves.
.PP
\fB-xrandr\fR \fI[mode]\fR
.IP
If the display supports the XRANDR (X Resize, Rotate
and Reflection) extension, and you expect XRANDR events
to occur to the display while x11vnc is running, this
options indicates x11vnc should try to respond to
them (as opposed to simply crashing by assuming the
old screen size). See the
.IR xrandr (1)
manpage and run
\'xrandr \fB-q'\fR for more info. [mode] is optional and
described below.
.IP
Since watching for XRANDR events and trapping errors
increases polling overhead, only use this option if
XRANDR changes are expected. For example on a rotatable
screen PDA or laptop, or using a XRANDR-aware Desktop
where you resize often. It is best to be viewing with a
vncviewer that supports the NewFBSize encoding, since it
knows how to react to screen size changes. Otherwise,
libvncserver tries to do so something reasonable for
viewers that cannot do this (portions of the screen
may be clipped, unused, etc).
.IP
"mode" defaults to "resize", which means create a
new, resized, framebuffer and hope all viewers can cope
with the change. "newfbsize" means first disconnect
all viewers that do not support the NewFBSize VNC
encoding, and then resize the framebuffer. "exit"
means disconnect all viewer clients, and then terminate
x11vnc.
.PP
\fB-padgeom\fR \fIWxH\fR
.IP
Whenever a new vncviewer connects, the framebuffer is
replaced with a fake, solid black one of geometry WxH.
Shortly afterwards the framebuffer is replaced with the
real one. This is intended for use with vncviewers
that do not support NewFBSize and one wants to make
sure the initial viewer geometry will be big enough
to handle all subsequent resizes (e.g. under \fB-xrandr,\fR
\fB-remote\fR id:windowid, rescaling, etc.)
.PP
\fB-o\fR \fIlogfile\fR
.IP
Write stderr messages to file \fIlogfile\fR instead of
to the terminal. Same as "\fB-logfile\fR \fIfile\fR". To append
to the file use "\fB-oa\fR \fIfile\fR" or "\fB-logappend\fR \fIfile\fR".
.PP
\fB-rc\fR \fIfilename\fR
.IP
Use \fIfilename\fR instead of $HOME/.x11vncrc for rc file.
.PP
\fB-norc\fR
.IP
Do not process any .x11vncrc file for options.
.PP
\fB-h,\fR \fB-help\fR
.IP
Print this help text.
-?, \fB-opts\fR Only list the x11vnc options.
.PP
\fB-V,\fR \fB-version\fR
.IP
Print program version and last modification date.
.PP
\fB-q\fR
.IP
Be quiet by printing less informational output to
stderr. Same as \fB-quiet.\fR
.PP
\fB-bg\fR
.IP
Go into the background after screen setup. Messages to
stderr are lost unless \fB-o\fR logfile is used. Something
like this could be useful in a script:
.IP
port=`ssh $host "x11vnc -display :0 -bg" | grep PORT`
.IP
port=`echo "$port" | sed -e 's/PORT=//'`
.IP
port=`expr $port - 5900`
.IP
vncviewer $host:$port
.PP
\fB-modtweak,\fR \fB-nomodtweak\fR
.IP
Option \fB-modtweak\fR automatically tries to adjust the AltGr
and Shift modifiers for differing language keyboards
between client and host. Otherwise, only a single key
press/release of a Keycode is simulated (i.e. ignoring
the state of the modifiers: this usually works for
identical keyboards). Also useful in resolving cases
where a Keysym is bound to multiple keys (e.g. "<" + ">"
and "," + "<" keys). Default: \fB-modtweak\fR
.PP
\fB-xkb\fR
.IP
When in modtweak mode, use the XKEYBOARD extension (if
the X display supports it) to do the modifier tweaking.
This is powerful and should be tried if there are still
keymapping problems when using \fB-modtweak\fR by itself.
.PP
\fB-skip_keycodes\fR \fIstring\fR
.IP
Ignore the comma separated list of decimal keycodes.
Perhaps these are keycodes not on your keyboard but
your X server thinks exist. Currently only applies
to \fB-xkb\fR mode. Use this option to help x11vnc in the
reverse problem it tries to solve: Keysym -> Keycode(s)
when ambiguities exist (more than one Keycode per
Keysym). Run 'xmodmap \fB-pk'\fR to see your keymapping.
Example: "\fB-skip_keycodes\fR \fI94,114\fR"
.PP
\fB-add_keysyms\fR
.IP
If a Keysym is received from a VNC viewer and
that Keysym does not exist in the X server, then
add the Keysym to the X server's keyboard mapping.
Added Keysyms will be removed when x11vnc exits.
.PP
\fB-clear_mods\fR
.IP
At startup and exit clear the modifier keys by sending
KeyRelease for each one. The Lock modifiers are skipped.
Used to clear the state if the display was accidentally
left with any pressed down.
.PP
\fB-clear_keys\fR
.IP
As \fB-clear_mods,\fR except try to release any pressed key.
Note that this option and \fB-clear_mods\fR can interfere
with a person typing at the physical keyboard.
.PP
\fB-remap\fR \fIstring\fR
.IP
Read Keysym remappings from file named \fIstring\fR.
Format is one pair of Keysyms per line (can be name
or hex value) separated by a space. If no file named
\fIstring\fR exists, it is instead interpreted as this
form: key1-key2,key3-key4,... See <X11/keysymdef.h>
header file for a list of Keysym names, or use
.IR xev (1).
To map a key to a button click, use the fake Keysyms
"Button1", ..., etc. E.g: "\fB-remap\fR \fISuper_R-Button2\fR"
(useful for pasting on a laptop)
.PP
\fB-norepeat,\fR \fB-repeat\fR
.IP
Option \fB-norepeat\fR disables X server key auto repeat
when VNC clients are connected. This works around a
repeating keystrokes bug (triggered by long processing
delays between key down and key up client events:
either from large screen changes or high latency).
Note: your VNC viewer side will likely do autorepeating,
so this is no loss unless someone is simultaneously at
the real X display. Default: \fB-norepeat\fR
.PP
\fB-nofb\fR
.IP
Ignore video framebuffer: only process keyboard and
pointer. Intended for use with Win2VNC and x2vnc
dual-monitor setups.
.PP
\fB-nobell\fR
.IP
Do not watch for XBell events. (no beeps will be heard)
Note: XBell monitoring requires the XKEYBOARD extension.
.PP
\fB-nosel\fR
.IP
Do not manage exchange of X selection/cutbuffer between
VNC viewers and the X server.
.PP
\fB-noprimary\fR
.IP
Do not poll the PRIMARY selection for changes to send
back to clients. (PRIMARY is still set on received
changes, however).
.PP
\fB-cursor\fR \fI[mode],\fR \fB-nocursor\fR
.IP
Sets how the pointer cursor shape (little icon at the
mouse pointer) should be handled. The "mode" string
is optional and is described below. The default
is to show some sort of cursor shape(s). How this
is done depends on the VNC viewer and the X server.
Use \fB-nocursor\fR to disable cursor shapes completely.
.IP
Some VNC viewers support the TightVNC CursorPosUpdates
and CursorShapeUpdates extensions (cuts down on
network traffic by not having to send the cursor image
every time the pointer is moved), in which case these
extensions are used (see \fB-nocursorshape\fR and \fB-nocursorpos\fR
below to disable). For other viewers the cursor shape
is written directly to the framebuffer every time the
pointer is moved or changed and gets sent along with
the other framebuffer updates. In this case, there
will be some lag between the vnc viewer pointer and
the remote cursor position.
.IP
If the X display supports retrieving the cursor shape
information from the X server, then the default is
to use that mode. On Solaris this can be done with
the SUN_OVL extension using \fB-overlay\fR (see also the
\fB-overlay_nomouse\fR option). A similar overlay scheme
is used on IRIX. Xorg (e.g. Linux) and recent Solaris
Xsun servers support the XFIXES extension to retrieve
the exact cursor shape from the X server. If XFIXES
is present it is preferred over Overlay and is used by
default (see \fB-noxfixes\fR below). This can be disabled
with \fB-nocursor,\fR and also some values of the "mode"
option below.
.IP
Note that under XFIXES cursors with transparency (alpha
channel) will not be exactly represented and one may
find Overlay preferable. See also the \fB-alphacut\fR and
\fB-alphafrac\fR options below as fudge factors to try to
improve the situation for cursors with transparency
for a given theme.
.IP
The "mode" string can be used to fine-tune the
displaying of cursor shapes. It can be used the
following ways:
.IP
"\fB-cursor\fR \fIarrow\fR" - just show the standard arrow
nothing more or nothing less.
.IP
"\fB-cursor\fR \fInone\fR" - same as "\fB-nocursor\fR"
.IP
"\fB-cursor\fR \fIX\fR" - when the cursor appears to be on the
root window, draw the familiar X shape. Some desktops
such as GNOME cover up the root window completely,
and so this will not work, try "X1", etc, to try to
shift the tree depth. On high latency links or slow
machines there will be a time lag between expected and
the actual cursor shape.
.IP
"\fB-cursor\fR \fIsome\fR" - like "X" but use additional
heuristics to try to guess if the window should have
a windowmanager-like resizer cursor or a text input
I-beam cursor. This is a complete hack, but may be
useful in some situations because it provides a little
more feedback about the cursor shape.
.IP
"\fB-cursor\fR \fImost\fR" - try to show as many cursors as
possible. Often this will only be the same as "some"
unless the display has overlay visuals or XFIXES
extensions available. On Solaris and IRIX if XFIXES
is not available, \fB-overlay\fR mode will be attempted.
.PP
\fB-noxfixes\fR
.IP
Do not use the XFIXES extension to draw the exact cursor
shape even if it is available.
.PP
\fB-alphacut\fR \fIn\fR
.IP
When using the XFIXES extension for the cursor shape,
cursors with transparency will not be displayed exactly
(but opaque ones will). This option sets n as a cutoff
for cursors that have transparency ("alpha channel"
with values ranging from 0 to 255) Any cursor pixel with
alpha value less than n becomes completely transparent.
Otherwise the pixel is completely opaque. Default 240
.IP
Note: the options \fB-alphacut,\fR \fB-alphafrac,\fR and \fB-alphafrac\fR
may be removed if a more accurate internal method for
handling cursor transparency is implemented.
.PP
\fB-alphafrac\fR \fIfraction\fR
.IP
With the threshold in \fB-alphacut\fR some cursors will become
almost completely transparent because their alpha values
are not high enough. For those cursors adjust the
alpha threshold until fraction of the non-zero alpha
channel pixels become opaque. Default 0.33
.PP
\fB-alpharemove\fR
.IP
By default, XFIXES cursors pixels with transparency have
the alpha factor multiplied into the RGB color values
(i.e. that corresponding to blending the cursor with a
black background). Specify this option to remove the
alpha factor. (useful for light colored semi-transparent
cursors).
.PP
\fB-noalphablend\fR
.IP
In XFIXES mode do not send cursor alpha channel data
to libvncserver. The default is to send it. The
alphablend effect will only be visible in \fB-nocursorshape\fR
mode or for clients with cursorshapeupdates turned
off. (However there is a hack for 32bpp with depth 24,
it uses the extra 8 bits to store cursor transparency
for use with a hacked vncviewer that applies the
transparency locally. See the FAQ for more info).
.PP
\fB-nocursorshape\fR
.IP
Do not use the TightVNC CursorShapeUpdates extension
even if clients support it. See \fB-cursor\fR above.
.PP
\fB-cursorpos,\fR \fB-nocursorpos\fR
.IP
Option \fB-cursorpos\fR enables sending the X cursor position
back to all vnc clients that support the TightVNC
CursorPosUpdates extension. Other clients will be able
to see the pointer motions. Default: \fB-cursorpos\fR
.PP
\fB-xwarppointer\fR
.IP
Move the pointer with
.IR XWarpPointer (3X)
instead of
the XTEST extension. Use this as a workaround
if the pointer motion behaves incorrectly, e.g.
on touchscreens or other non-standard setups.
Also sometimes needed on XINERAMA displays.
.PP
\fB-buttonmap\fR \fIstring\fR
.IP
String to remap mouse buttons. Format: IJK-LMN, this
maps buttons I -> L, etc., e.g. \fB-buttonmap\fR 13-31
.IP
Button presses can also be mapped to keystrokes: replace
a button digit on the right of the dash with :<sym>:
or :<sym1>+<sym2>: etc. for multiple keys. For example,
if the viewing machine has a mouse-wheel (buttons 4 5)
but the x11vnc side does not, these will do scrolls:
.IP
\fB-buttonmap\fR 12345-123:Prior::Next:
.IP
\fB-buttonmap\fR 12345-123:Up+Up+Up::Down+Down+Down:
.IP
See <X11/keysymdef.h> header file for a list of Keysyms,
or use the
.IR xev (1)
program. Note: mapping of button
clicks to Keysyms may not work if \fB-modtweak\fR or \fB-xkb\fR is
needed for the Keysym.
.IP
If you include a modifier like "Shift_L" the
modifier's up/down state is toggled, e.g. to send
"The" use :Shift_L+t+Shift_L+h+e: (the 1st one is
shift down and the 2nd one is shift up). (note: the
initial state of the modifier is ignored and not reset)
To include button events use "Button1", ... etc.
.PP
\fB-nodragging\fR
.IP
Do not update the display during mouse dragging events
(mouse button held down). Greatly improves response on
slow setups, but you lose all visual feedback for drags,
text selection, and some menu traversals. It overrides
any \fB-pointer_mode\fR setting
.PP
\fB-pointer_mode\fR \fIn\fR
.IP
Various pointer motion update schemes. "\fB-pm\fR" is
an alias. The problem is pointer motion can cause
rapid changes on the screen: consider the rapid changes
when you drag a large window around. Neither x11vnc's
screen polling and vnc compression routines nor the
bandwidth to the vncviewers can keep up these rapid
screen changes: everything will bog down when dragging
or scrolling. So a scheme has to be used to "eat"
much of that pointer input before re-polling the screen
and sending out framebuffer updates. The mode number
\fIn\fR can be 0 to 4 and selects one of the schemes
desribed below.
.IP
n=0: does the same as \fB-nodragging.\fR (all screen polling
is suspended if a mouse button is pressed.)
.IP
n=1: was the original scheme used to about Jan 2004:
it basically just skips \fB-input_skip\fR keyboard or pointer
events before repolling the screen.
.IP
n=2 is an improved scheme: by watching the current rate
of input events it tries to detect if it should try to
"eat" additional pointer events before continuing.
.IP
n=3 is basically a dynamic \fB-nodragging\fR mode: it detects
when the mouse motion has paused and then refreshes
the display.
.IP
n=4: attempts to measures network rates and latency,
the video card read rate, and how many tiles have been
changed on the screen. From this, it aggressively tries
to push screen "frames" when it decides it has enough
resources to do so. NOT FINISHED.
.IP
The default n is 2. Note that modes 2, 3, 4 will skip
\fB-input_skip\fR keyboard events (but it will not count
pointer events). Also note that these modes are not
available in \fB-threads\fR mode which has its own pointer
event handling mechanism.
.IP
To try out the different pointer modes to see which
one gives the best response for your usage, it is
convenient to use the remote control function, for
example "x11vnc \fB-R\fR pm:4" or the tcl/tk gui (Tuning ->
pointer_mode -> n).
.PP
\fB-input_skip\fR \fIn\fR
.IP
For the pointer handling when non-threaded: try to
read n user input events before scanning display. n < 0
means to act as though there is always user input.
Default: 10
.PP
\fB-speeds\fR \fIrd,bw,lat\fR
.IP
x11vnc tries to estimate some speed parameters that
are used to optimize scheduling (e.g. \fB-pointer_mode\fR
4) and other things. Use the \fB-speeds\fR option to set
these manually. The triple \fIrd,bw,lat\fR corresponds
to video h/w read rate in MB/sec, network bandwidth to
clients in KB/sec, and network latency to clients in
milliseconds, respectively. If a value is left blank,
e.g. "\fB-speeds\fR \fI,100,15\fR", then the internal scheme is
used to estimate the empty value(s).
.IP
Typical PC video cards have read rates of 5-10 MB/sec.
If the framebuffer is in main memory instead of video
h/w (e.g. SunRay, shadowfb, Xvfb), the read rate may
be much faster. "x11perf \fB-getimage500"\fR can be used
to get a lower bound (remember to factor in the bytes
per pixel). It is up to you to estimate the network
bandwith to clients. For the latency the
.IR ping (1)
command can be used.
.IP
For convenience there are some aliases provided,
e.g. "\fB-speeds\fR \fImodem\fR". The aliases are: "modem" for
6,4,200; "dsl" for 6,100,50; and "lan" for 6,5000,1
.PP
\fB-debug_pointer\fR
.IP
Print debugging output for every pointer event.
.PP
\fB-debug_keyboard\fR
.IP
Print debugging output for every keyboard event.
.PP
Same as \fB-dp\fR and \fB-dk,\fR respectively. Use multiple
times for more output.
.PP
\fB-defer\fR \fItime\fR
.IP
Time in ms to wait for updates before sending to client
(deferUpdateTime) Default: 30
.PP
\fB-wait\fR \fItime\fR
.IP
Time in ms to pause between screen polls. Used to cut
down on load. Default: 30
.PP
\fB-nap\fR
.IP
Monitor activity and if it is low take longer naps
.PP
\fB-nonap\fR
.IP
between screen polls to really cut down load when idle.
Default: take naps
.PP
\fB-sb\fR \fItime\fR
.IP
Time in seconds after NO activity (e.g. screen blank)
to really throttle down the screen polls (i.e. sleep
for about 1.5 secs). Use 0 to disable. Default: 60
.PP
\fB-sigpipe\fR \fIstring\fR
.IP
Broken pipe (SIGPIPE) handling. \fIstring\fR can be
"ignore" or "exit". For "ignore" libvncserver
will handle the abrupt loss of a client and continue,
for "exit" x11vnc will cleanup and exit at the 1st
broken connection. Default: "ignore".
.PP
\fB-threads,\fR \fB-nothreads\fR
.IP
Whether or not to use the threaded libvncserver
algorithm [rfbRunEventLoop] if libpthread is available
Default: \fB-nothreads\fR
.PP
\fB-fs\fR \fIf\fR
.IP
If the fraction of changed tiles in a poll is greater
than f, the whole screen is updated. Default: 0.75
.PP
\fB-gaps\fR \fIn\fR
.IP
Heuristic to fill in gaps in rows or cols of n or
less tiles. Used to improve text paging. Default: 4
.PP
\fB-grow\fR \fIn\fR
.IP
Heuristic to grow islands of changed tiles n or wider
by checking the tile near the boundary. Default: 3
.PP
\fB-fuzz\fR \fIn\fR
.IP
Tolerance in pixels to mark a tiles edges as changed.
Default: 2
.PP
\fB-snapfb\fR
.IP
Instead of polling the X display framebuffer (fb) for
changes, periodically copy all of X display fb into main
memory and examine that copy for changes. Under some
circumstances this will improve interactive response,
or at least make things look smoother, but in others
(many) it will make the response worse. If the video
h/w fb is such that reading small tiles is very slow
this mode could help. To keep the "framerate" up
the screen size x bpp cannot be too large. Note that
this mode is very wasteful of memory I/O resources
(it makes full screen copies even if nothing changes).
It may be of use in video capture-like applications,
or where window tearing is a problem.
.PP
\fB-gui\fR \fI[gui-opts]\fR
.IP
Start up a simple tcl/tk gui based on the the remote
control options \fB-remote/-query\fR described below.
Requires the "wish" program to be installed on the
machine. "gui-opts" is not required: the default is
to start up both the gui and x11vnc with the gui showing
up on the X display in the environment variable DISPLAY.
.IP
"gui-opts" can be a comma separated list of items.
Currently there are these types of items: 1) a gui mode,
a 2) gui "simplicity", and 3) the X display the gui
should display on.
.IP
1) The gui mode can be "start", "conn", or "wait"
"start" is the default mode above and is not required.
"conn" means do not automatically start up x11vnc,
but instead just try to connect to an existing x11vnc
process. "wait" means just start the gui and nothing
else (you will later instruct the gui to start x11vnc
or connect to an existing one.)
.IP
2) The gui simplicity is off by default (a power-user
gui with all options is presented) To start with
something less daunting supply the string "simple"
("ez" is an alias for this). Once the gui is
started you can toggle between the two with "Misc ->
simple_gui".
.IP
3) Note the possible confusion regarding the potentially
two different X displays: x11vnc polls one, but you
may want the gui to appear on another. For example, if
you ssh in and x11vnc is not running yet you may want
the gui to come back to you via your ssh redirected X
display (e.g. localhost:10).
.IP
Examples: "x11vnc \fB-gui",\fR "x11vnc \fB-gui\fR ez"
"x11vnc \fB-gui\fR localhost:10", "x11vnc \fB-gui\fR conn,host:0"
.IP
If you do not specify a gui X display in "gui-opts"
then the DISPLAY environment variable and \fB-display\fR
option are tried (in that order). Regarding the x11vnc
X display the gui will try to connect to, it first
tries \fB-display\fR and then DISPLAY. For example, "x11vnc
\fB-display\fR :0 \fB-gui\fR otherhost:0", will remote control an
x11vnc polling :0 and display the gui on otherhost:0
.IP
If you do not intend to start x11vnc from the gui
(i.e. just remote control an existing one), then the
gui process can run on a different machine from the
x11vnc server as long as X permissions, etc. permit
communication between the two.
.PP
\fB-remote\fR \fIcommand\fR
.IP
Remotely control some aspects of an already running
x11vnc server. "\fB-R\fR" and "\fB-r\fR" are aliases for
"\fB-remote\fR". After the remote control command is
sent to the running server the 'x11vnc \fB-remote\fR ...'
command exits. You can often use the \fB-query\fR command
(see below) to see if the x11vnc server processed your
\fB-remote\fR command.
.IP
The default communication channel is that of X
properties (specifically VNC_CONNECT), and so this
command must be run with correct settings for DISPLAY
and possibly XAUTHORITY to connect to the X server
and set the property. Alternatively, use the \fB-display\fR
and \fB-auth\fR options to set them to the correct values.
The running server cannot use the \fB-novncconnect\fR option
because that disables the communication channel.
See below for alternate channels.
.IP
For example: 'x11vnc \fB-remote\fR stop' (which is the same as
\'x11vnc \fB-R\fR stop') will close down the x11vnc server.
\'x11vnc \fB-R\fR shared' will enable shared connections, and
\'x11vnc \fB-R\fR scale:3/4' will rescale the desktop.
.IP
Note: the more drastic the change induced by the \fB-remote\fR
command, the bigger the chance for bugs or crashes.
Please report reproducible bugs.
.IP
.IP
The following \fB-remote/-R\fR commands are supported:
.IP
stop terminate the server, same as "quit"
"exit" or "shutdown".
.IP
ping see if the x11vnc server responds.
Return is: ans=ping:<xdisplay>
.IP
blacken try to push a black fb update to all
clients (due to timings a client
could miss it). Same as "zero", also
"zero:x1,y1,x2,y2" for a rectangle.
.IP
refresh send the entire fb to all clients.
.IP
reset recreate the fb, polling memory, etc.
.IP
id:windowid set \fB-id\fR window to "windowid". empty
or "root" to go back to root window
.IP
sid:windowid set \fB-sid\fR window to "windowid"
.IP
flashcmap enable \fB-flashcmap\fR mode.
.IP
noflashcmap disable \fB-flashcmap\fR mode.
.IP
notruecolor enable \fB-notruecolor\fR mode.
.IP
truecolor disable \fB-notruecolor\fR mode.
.IP
overlay enable \fB-overlay\fR mode (if applicable).
.IP
nooverlay disable \fB-overlay\fR mode.
.IP
overlay_cursor in \fB-overlay\fR mode, enable cursor drawing.
.IP
overlay_nocursor disable cursor drawing. same as
nooverlay_cursor.
.IP
visual:vis set \fB-visual\fR to "vis"
.IP
scale:frac set \fB-scale\fR to "frac"
.IP
viewonly enable \fB-viewonly\fR mode.
.IP
noviewonly disable \fB-viewonly\fR mode.
.IP
shared enable \fB-shared\fR mode.
.IP
noshared disable \fB-shared\fR mode.
.IP
forever enable \fB-forever\fR mode.
.IP
noforever disable \fB-forever\fR mode.
.IP
timeout:n reset \fB-timeout\fR to n, if there are
currently no clients, exit unless one
connects in the next n secs.
.IP
deny deny any new connections, same as "lock"
.IP
nodeny allow new connections, same as "unlock"
.IP
connect:host do reverse connection to host, "host"
may be a comma separated list of hosts
or host:ports. See \fB-connect.\fR
.IP
disconnect:host disconnect any clients from "host"
same as "close:host". Use host
"all" to close all current clients.
If you know the client internal hex ID,
e.g. 0x3 (returned by \fB-query\fR clients and
RFB_CLIENT_ID), you can use that too.
.IP
allowonce:host For the next connection only, allow
connection from "host".
.IP
allow:hostlist set \fB-allow\fR list to (comma separated)
"hostlist". See \fB-allow\fR and \fB-localhost.\fR
Do not use with \fB-allow\fR /path/to/file
Use "+host" to add a single host, and
use "\fB-host\fR" to delete a single host
.IP
localhost enable \fB-localhost\fR mode
.IP
nolocalhost disable \fB-localhost\fR mode
.IP
input:str set \fB-input\fR to "str", empty to disable.
.IP
client_input:str set the K, M, B \fB-input\fR on a per-client
basis. select which client as for
disconnect, e.g. client_input:host:MB
or client_input:0x2:K
.IP
accept:cmd set \fB-accept\fR "cmd" (empty to disable).
.IP
gone:cmd set \fB-gone\fR "cmd" (empty to disable).
.IP
noshm enable \fB-noshm\fR mode.
.IP
shm disable \fB-noshm\fR mode (i.e. use shm).
.IP
flipbyteorder enable \fB-flipbyteorder\fR mode, you may need
to set noshm for this to do something.
.IP
noflipbyteorder disable \fB-flipbyteorder\fR mode.
.IP
onetile enable \fB-onetile\fR mode. (you may need to
set shm for this to do something)
.IP
noonetile disable \fB-onetile\fR mode.
.IP
solid enable \fB-solid\fR mode
.IP
nosolid disable \fB-solid\fR mode.
.IP
solid_color:color set \fB-solid\fR color (and apply it).
.IP
blackout:str set \fB-blackout\fR "str" (empty to disable).
See \fB-blackout\fR for the form of "str"
(basically: WxH+X+Y,...)
Use "+WxH+X+Y" to append a single
rectangle use "-WxH+X+Y" to delete one
.IP
xinerama enable \fB-xinerama\fR mode. (if applicable)
.IP
noxinerama disable \fB-xinerama\fR mode.
.IP
xrandr enable \fB-xrandr\fR mode. (if applicable)
.IP
noxrandr disable \fB-xrandr\fR mode.
.IP
xrandr_mode:mode set the \fB-xrandr\fR mode to "mode".
.IP
padgeom:WxH set \fB-padgeom\fR to WxH (empty to disable)
If WxH is "force" or "do" the padded
geometry fb is immediately applied.
.IP
quiet enable \fB-quiet\fR mode.
.IP
noquiet disable \fB-quiet\fR mode.
.IP
modtweak enable \fB-modtweak\fR mode.
.IP
nomodtweak enable \fB-nomodtweak\fR mode.
.IP
xkb enable \fB-xkb\fR modtweak mode.
.IP
noxkb disable \fB-xkb\fR modtweak mode.
.IP
skip_keycodes:str enable \fB-xkb\fR \fB-skip_keycodes\fR "str".
.IP
add_keysyms enable \fB-add_keysyms\fR mode.
.IP
noadd_keysyms stop adding keysyms. those added will
still be removed at exit.
.IP
clear_mods enable \fB-clear_mods\fR mode and clear them.
.IP
noclear_mods disable \fB-clear_mods\fR mode.
.IP
clear_keys enable \fB-clear_keys\fR mode and clear them.
.IP
noclear_keys disable \fB-clear_keys\fR mode.
.IP
remap:str set \fB-remap\fR "str" (empty to disable).
See \fB-remap\fR for the form of "str"
(basically: key1-key2,key3-key4,...)
Use "+key1-key2" to append a single
keymapping, use "-key1-key2" to delete.
.IP
norepeat enable \fB-norepeat\fR mode.
.IP
repeat disable \fB-norepeat\fR mode.
.IP
nofb enable \fB-nofb\fR mode.
.IP
fb disable \fB-nofb\fR mode.
.IP
bell enable bell (if supported).
.IP
nobell disable bell.
.IP
nosel enable \fB-nosel\fR mode.
.IP
sel disable \fB-nosel\fR mode.
.IP
noprimary enable \fB-noprimary\fR mode.
.IP
primary disable \fB-noprimary\fR mode.
.IP
cursor:mode enable \fB-cursor\fR "mode".
.IP
show_cursor enable showing a cursor.
.IP
noshow_cursor disable showing a cursor. (same as
"nocursor")
.IP
xfixes enable xfixes cursor shape mode.
.IP
noxfixes disable xfixes cursor shape mode.
.IP
alphacut:n set \fB-alphacut\fR to n.
.IP
alphafrac:f set \fB-alphafrac\fR to f.
.IP
alpharemove enable \fB-alpharemove\fR mode.
.IP
noalpharemove disable \fB-alpharemove\fR mode.
.IP
alphablend disable \fB-noalphablend\fR mode.
.IP
noalphablend enable \fB-noalphablend\fR mode.
.IP
cursorshape disable \fB-nocursorshape\fR mode.
.IP
nocursorshape enable \fB-nocursorshape\fR mode.
.IP
cursorpos disable \fB-nocursorpos\fR mode.
.IP
nocursorpos enable \fB-nocursorpos\fR mode.
.IP
xwarp enable \fB-xwarppointer\fR mode.
.IP
noxwarp disable \fB-xwarppointer\fR mode.
.IP
buttonmap:str set \fB-buttonmap\fR "str", empty to disable
.IP
dragging disable \fB-nodragging\fR mode.
.IP
nodragging enable \fB-nodragging\fR mode.
.IP
pointer_mode:n set \fB-pointer_mode\fR to n. same as "pm"
.IP
input_skip:n set \fB-input_skip\fR to n.
.IP
speeds:str set \fB-speeds\fR to str.
.IP
debug_pointer enable \fB-debug_pointer,\fR same as "dp"
.IP
nodebug_pointer disable \fB-debug_pointer,\fR same as "nodp"
.IP
debug_keyboard enable \fB-debug_keyboard,\fR same as "dk"
.IP
nodebug_keyboard disable \fB-debug_keyboard,\fR same as "nodk"
.IP
defer:n set \fB-defer\fR to n ms,same as deferupdate:n
.IP
wait:n set \fB-wait\fR to n ms.
.IP
rfbwait:n set \fB-rfbwait\fR (rfbMaxClientWait) to n ms.
.IP
nap enable \fB-nap\fR mode.
.IP
nonap disable \fB-nap\fR mode.
.IP
sb:n set \fB-sb\fR to n s, same as screen_blank:n
.IP
fs:frac set \fB-fs\fR fraction to "frac", e.g. 0.5
.IP
gaps:n set \fB-gaps\fR to n.
.IP
grow:n set \fB-grow\fR to n.
.IP
fuzz:n set \fB-fuzz\fR to n.
.IP
snapfb enable \fB-snapfb\fR mode.
.IP
nosnapfb disable \fB-snapfb\fR mode.
.IP
progressive:n set libvncserver \fB-progressive\fR slice
height parameter to n.
.IP
desktop:str set \fB-desktop\fR name to str for new clients.
.IP
rfbport:n set \fB-rfbport\fR to n.
.IP
http enable http client connections.
.IP
nohttp disable http client connections.
.IP
httpport:n set \fB-httpport\fR to n.
.IP
httpdir:dir set \fB-httpdir\fR to dir (and enable http).
.IP
enablehttpproxy enable \fB-enablehttpproxy\fR mode.
.IP
noenablehttpproxy disable \fB-enablehttpproxy\fR mode.
.IP
alwaysshared enable \fB-alwaysshared\fR mode.
.IP
noalwaysshared disable \fB-alwaysshared\fR mode.
(may interfere with other options)
.IP
nevershared enable \fB-nevershared\fR mode.
.IP
nonevershared disable \fB-nevershared\fR mode.
(may interfere with other options)
.IP
dontdisconnect enable \fB-dontdisconnect\fR mode.
.IP
nodontdisconnect disable \fB-dontdisconnect\fR mode.
(may interfere with other options)
.IP
noremote disable the \fB-remote\fR command processing,
it cannot be turned back on.
.IP
.IP
The
.IR vncconnect (1)
command from standard VNC
.IP
distributions may also be used if string is prefixed
.IP
with "cmd=" E.g. 'vncconnect cmd=stop'. Under some
.IP
circumstances
.IR xprop (1)
can used if it supports \fB-set\fR
.IP
(see the FAQ).
.IP
.IP
If "\fB-connect\fR \fI/path/to/file\fR" has been supplied to the
.IP
running x11vnc server then that file can be used as a
.IP
communication channel (this is the only way to remote
.IP
control one of many x11vnc's polling the same X display)
.IP
Simply run: 'x11vnc \fB-connect\fR /path/to/file \fB-remote\fR ...'
.IP
or you can directly write to the file via something
.IP
like: "echo cmd=stop > /path/to/file", etc.
.PP
\fB-query\fR \fIvariable\fR
.IP
Like \fB-remote,\fR except just query the value of
\fIvariable\fR. "\fB-Q\fR" is an alias for "\fB-query\fR".
Multiple queries can be done by separating variables
by commas, e.g. \fB-query\fR var1,var2. The results come
back in the form ans=var1:value1,ans=var2:value2,...
to the standard output. If a variable is read-only,
it comes back with prefix "aro=" instead of "ans=".
.IP
Some \fB-remote\fR commands are pure actions that do not make
sense as variables, e.g. "stop" or "disconnect",
in these cases the value returned is "N/A". To direct
a query straight to the VNC_CONNECT property or connect
file use "qry=..." instead of "cmd=..."
.IP
Here is the current list of "variables" that can
be supplied to the \fB-query\fR command. This includes the
"N/A" ones that return no useful info. For variables
names that do not correspond to an x11vnc option or
remote command, we hope the name makes it obvious what
the returned value corresponds to (hint: the ext_*
variables correspond to the presence of X extensions):
.IP
ans= stop quit exit shutdown ping blacken zero
refresh reset close disconnect id sid waitmapped
nowaitmapped flashcmap noflashcmap truecolor notruecolor
overlay nooverlay overlay_cursor overlay_yescursor
nooverlay_nocursor nooverlay_cursor nooverlay_yescursor
overlay_nocursor visual scale viewonly noviewonly
shared noshared forever noforever once timeout deny
lock nodeny unlock connect allowonce allow localhost
nolocalhost accept gone shm noshm flipbyteorder
noflipbyteorder onetile noonetile solid_color solid
nosolid blackout xinerama noxinerama xrandr noxrandr
xrandr_mode padgeom quiet q noquiet modtweak nomodtweak
xkb noxkb skip_keycodes add_keysyms noadd_keysyms
clear_mods noclear_mods clear_keys noclear_keys
remap repeat norepeat fb nofb bell nobell sel
nosel primary noprimary cursorshape nocursorshape
cursorpos nocursorpos cursor show_cursor noshow_cursor
nocursor xfixes noxfixes alphacut alphafrac alpharemove
noalpharemove alphablend noalphablend xwarp xwarppointer
noxwarp noxwarppointer buttonmap dragging nodragging
pointer_mode pm input_skip input client_input speeds
debug_pointer dp nodebug_pointer nodp debug_keyboard dk
nodebug_keyboard nodk deferupdate defer wait rfbwait
nap nonap sb screen_blank fs gaps grow fuzz snapfb
nosnapfb progressive rfbport http nohttp httpport
httpdir enablehttpproxy noenablehttpproxy alwaysshared
noalwaysshared nevershared noalwaysshared dontdisconnect
nodontdisconnect desktop noremote
.IP
aro= display vncdisplay desktopname http_url auth
users rootshift scale_str scaled_x scaled_y scale_numer
scale_denom scale_fac scaling_noblend scaling_nomult4
scaling_pad scaling_interpolate inetd safer unsafe
passwdfile using_shm logfile o rc norc h help V version
lastmod bg sigpipe threads clients client_count pid
ext_xtest ext_xkb ext_xshm ext_xinerama ext_overlay
ext_xfixes ext_xdamage ext_xrandr rootwin num_buttons
button_mask mouse_x mouse_y bpp depth indexed_color
dpy_x dpy_y rfbauth passwd
.PP
\fB-sync\fR
.IP
By default \fB-remote\fR commands are run asynchronously, that
is, the request is posted and the program immediately
exits. Use \fB-sync\fR to have the program wait for an
acknowledgement from the x11vnc server that command
was processed. On the other hand \fB-query\fR requests are
always processed synchronously because they have wait
for the result.
.IP
Also note that if both \fB-remote\fR and \fB-query\fR requests are
supplied on the command line, the \fB-remote\fR is processed
first (synchronously: no need for \fB-sync),\fR and then
the \fB-query\fR request is processed in the normal way.
This allows for a reliable way to see if the \fB-remote\fR
command was processed by querying for any new settings.
Note however that there is timeout of a few seconds so
if the x11vnc takes longer than that to process the
requests the requestor will think that a failure has
taken place.
.PP
\fB-noremote\fR
.IP
Do not process any remote control commands or queries.
.IP
A note about security wrt remote control commands.
If someone can connect to the X display and change the
property VNC_CONNECT, then they can remotely control
x11vnc. Normally access to the X display is protected.
Note that if they can modify VNC_CONNECT, they could
also run their own x11vnc and have complete control
of the desktop. If the "\fB-connect\fR \fI/path/to/file\fR"
channel is being used, obviously anyone who can
write to /path/to/file can remotely control x11vnc.
So be sure to protect the X display and that file's
write permissions.
.IP
To disable the VNC_CONNECT property channel completely
use \fB-novncconnect.\fR
.PP
\fB-unsafe\fR
.IP
If x11vnc is running as root (e.g. inetd or Xsetup for
a display manager) a few remote commands are disabled
(currently: id:pick, accept:<cmd>, and gone:<cmd>)
because they are associated with running external
programs. If you specify \fB-unsafe,\fR then these remote
control commands are allowed when running as root.
When running as non-root all commands are allowed.
See \fB-safer\fR below.
.PP
\fB-safer\fR
.IP
Even if not running as root, disable the above unsafe
remote control commands.
.PP
\fB-deny_all\fR
.IP
For use with \fB-remote\fR nodeny: start out denying all
incoming clients until "\fB-remote\fR \fInodeny\fR" is used to
let them in.
.PP
These options are passed to libvncserver:
.PP
\fB-rfbport\fR \fIport\fR
.IP
TCP port for RFB protocol
.PP
\fB-rfbwait\fR \fItime\fR
.IP
max time in ms to wait for RFB client
.PP
\fB-rfbauth\fR \fIpasswd-file\fR
.IP
use authentication on RFB protocol
(use 'storepasswd' to create a password file)
.PP
\fB-passwd\fR \fIplain-password\fR
.IP
use authentication
(use plain-password as password, USE AT YOUR RISK)
.PP
\fB-deferupdate\fR \fItime\fR
.IP
time in ms to defer updates (default 40)
.PP
\fB-desktop\fR \fIname\fR
.IP
VNC desktop name (default "LibVNCServer")
.PP
\fB-alwaysshared\fR
.IP
always treat new clients as shared
.PP
\fB-nevershared\fR
.IP
never treat new clients as shared
.PP
\fB-dontdisconnect\fR
.IP
don't disconnect existing clients when a new non-shared
connection comes in (refuse new connection instead)
.PP
\fB-httpdir\fR \fIdir-path\fR
.IP
enable http server using dir-path home
.PP
\fB-httpport\fR \fIportnum\fR
.IP
use portnum for http connection
.PP
\fB-enablehttpproxy\fR
.IP
enable http proxy support
.PP
\fB-progressive\fR \fIheight\fR
.IP
enable progressive updating for slow links
.SH "FILES"
.IR $HOME/.x11vncrc ,
.IR $HOME/.Xauthority
.SH "ENVIRONMENT"
.IR DISPLAY ,
.IR XAUTHORITY ,
.IR HOME
.PP
The following are set for the auxiliary commands
run by \fB-accept\fR and \fB-gone\fR:
.PP
.IR RFB_CLIENT_IP ,
.IR RFB_CLIENT_PORT ,
.IR RFB_SERVER_IP ,
.IR RFB_SERVER_PORT ,
.IR RFB_X11VNC_PID ,
.IR RFB_CLIENT_ID ,
.IR RFB_CLIENT_COUNT ,
.IR RFB_MODE
.SH "SEE ALSO"
.IR vncviewer (1),
.IR vncpasswd (1),
.IR vncconnect (1),
.IR vncserver (1),
.IR Xvnc (1),
.IR inetd (1),
.IR xev (1),
.IR xmodmap (1),
.IR Xserver (1),
.IR xauth (1),
.IR xhost (1),
.IR Xsecurity (7),
.IR xmessage (1),
.IR ipcrm (1),
.IR http://www.tightvnc.com ,
.IR http://www.realvnc.com ,
.IR http://www.karlrunge.com/x11vnc/ ,
.IR http://www.karlrunge.com/x11vnc/#faq
.SH AUTHORS
x11vnc was written by Karl J. Runge <runge@karlrunge.com>,
it is part of the LibVNCServer project <http://sf.net/projects/libvncserver>.
This manual page is based one the one written by Ludovic Drolez
<ldrolez@debian.org>, for the Debian project (both may be used by others).
|