Fossil SCM

Add documentation for the --transport-command options on the various sync commands. Improvements to the documentation of the sync protocol.

drh 2021-12-22 20:40 trunk

Commit 505d9d48eb5966c0bc04779e043eaf245f56e2554a28e3e6b29770932bd07107

Parent 14b3f48e3ca9b2a…

5 files changed +1 +1 -1 +7 -10 +12 -1 +60 -1

~ src/clone.c ~ src/http.c ~ src/http_transport.c ~ src/sync.c ~ www/sync.wiki

M src/clone.c

		--- src/clone.c
		+++ src/clone.c
		@@ -132,10 +132,11 @@
132	132	** --once Don't remember the URI.
133	133	** --private Also clone private branches
134	134	** --save-http-password Remember the HTTP password without asking
135	135	** --ssh-command\|-c SSH Use SSH as the "ssh" command
136	136	** --ssl-identity FILENAME Use the SSL identity if requested by the server
	137	+** --transport-command CMD Use CMD to move messages to the server and back
137	138	** -u\|--unversioned Also sync unversioned content
138	139	** -v\|--verbose Show more statistics in output
139	140	** --workdir DIR Also open a checkout in DIR
140	141	**
141	142	** See also: [[init]], [[open]]
142	143

	--- src/clone.c
	+++ src/clone.c
	@@ -132,10 +132,11 @@
132	** --once Don't remember the URI.
133	** --private Also clone private branches
134	** --save-http-password Remember the HTTP password without asking
135	** --ssh-command\|-c SSH Use SSH as the "ssh" command
136	** --ssl-identity FILENAME Use the SSL identity if requested by the server

137	** -u\|--unversioned Also sync unversioned content
138	** -v\|--verbose Show more statistics in output
139	** --workdir DIR Also open a checkout in DIR
140	**
141	** See also: [[init]], [[open]]
142

	--- src/clone.c
	+++ src/clone.c
	@@ -132,10 +132,11 @@
132	** --once Don't remember the URI.
133	** --private Also clone private branches
134	** --save-http-password Remember the HTTP password without asking
135	** --ssh-command\|-c SSH Use SSH as the "ssh" command
136	** --ssl-identity FILENAME Use the SSL identity if requested by the server
137	** --transport-command CMD Use CMD to move messages to the server and back
138	** -u\|--unversioned Also sync unversioned content
139	** -v\|--verbose Show more statistics in output
140	** --workdir DIR Also open a checkout in DIR
141	**
142	** See also: [[init]], [[open]]
143

M src/http.c

+1 -1

		--- src/http.c
		+++ src/http.c
		@@ -232,11 +232,11 @@
232	232	zFullUrl = url_full(&g.url);
233	233	zCmd = mprintf("%s %$ %$ %$", g.zHttpCmd, zFullUrl,zUplink,zDownlink);
234	234	fossil_free(zFullUrl);
235	235	blob_write_to_file(pSend, zUplink);
236	236	if( g.fHttpTrace ){
237		- fossil_print("RUN: %s\n", zCmd);
	237	+ fossil_print("RUN %s\n", zCmd);
238	238	}
239	239	rc = fossil_system(zCmd);
240	240	if( rc ){
241	241	fossil_warning("Transport command failed: %s\n", zCmd);
242	242	}
243	243

	--- src/http.c
	+++ src/http.c
	@@ -232,11 +232,11 @@
232	zFullUrl = url_full(&g.url);
233	zCmd = mprintf("%s %$ %$ %$", g.zHttpCmd, zFullUrl,zUplink,zDownlink);
234	fossil_free(zFullUrl);
235	blob_write_to_file(pSend, zUplink);
236	if( g.fHttpTrace ){
237	fossil_print("RUN: %s\n", zCmd);
238	}
239	rc = fossil_system(zCmd);
240	if( rc ){
241	fossil_warning("Transport command failed: %s\n", zCmd);
242	}
243

	--- src/http.c
	+++ src/http.c
	@@ -232,11 +232,11 @@
232	zFullUrl = url_full(&g.url);
233	zCmd = mprintf("%s %$ %$ %$", g.zHttpCmd, zFullUrl,zUplink,zDownlink);
234	fossil_free(zFullUrl);
235	blob_write_to_file(pSend, zUplink);
236	if( g.fHttpTrace ){
237	fossil_print("RUN %s\n", zCmd);
238	}
239	rc = fossil_system(zCmd);
240	if( rc ){
241	fossil_warning("Transport command failed: %s\n", zCmd);
242	}
243

M src/http_transport.c

+7 -10

		--- src/http_transport.c
		+++ src/http_transport.c
		@@ -141,12 +141,12 @@
141	141	if( pUrlData->path && pUrlData->path[0] ){
142	142	blob_append_escaped_arg(&zCmd, pUrlData->path, 1);
143	143	}else{
144	144	fossil_fatal("ssh:// URI does not specify a path to the repository");
145	145	}
146		- if( g.fSshTrace ){
147		- fossil_print("%s\n", blob_str(&zCmd)); /* Show the whole SSH command */
	146	+ if( g.fSshTrace \|\| g.fHttpTrace ){
	147	+ fossil_print("RUN %s\n", blob_str(&zCmd)); /* Show the whole SSH command */
148	148	}
149	149	popen2(blob_str(&zCmd), &sshIn, &sshOut, &sshPid, 0);
150	150	if( sshPid==0 ){
151	151	socket_set_errmsg("cannot start ssh tunnel using [%b]", &zCmd);
152	152	}
		@@ -177,19 +177,15 @@
177	177	#else
178	178	socket_set_errmsg("HTTPS: Fossil has been compiled without SSL support");
179	179	rc = 1;
180	180	#endif
181	181	}else if( pUrlData->isFile ){
182		- sqlite3_uint64 iRandId;
183	182	if( !db_looks_like_a_repository(pUrlData->name) ){
184	183	fossil_fatal("not a fossil repository: \"%s\"", pUrlData->name);
185	184	}
186		- sqlite3_randomness(sizeof(iRandId), &iRandId);
187		- transport.zOutFile = mprintf("%s-%llu-out.http",
188		- g.zRepositoryName, iRandId);
189		- transport.zInFile = mprintf("%s-%llu-in.http",
190		- g.zRepositoryName, iRandId);
	185	+ transport.zOutFile = fossil_temp_filename();
	186	+ transport.zInFile = fossil_temp_filename();
191	187	transport.pFile = fossil_fopen(transport.zOutFile, "wb");
192	188	if( transport.pFile==0 ){
193	189	fossil_fatal("cannot output temporary file: %s", transport.zOutFile);
194	190	}
195	191	transport.isOpen = 1;
		@@ -226,12 +222,12 @@
226	222	fclose(transport.pFile);
227	223	transport.pFile = 0;
228	224	}
229	225	file_delete(transport.zInFile);
230	226	file_delete(transport.zOutFile);
231		- free(transport.zInFile);
232		- free(transport.zOutFile);
	227	+ sqlite3_free(transport.zInFile);
	228	+ sqlite3_free(transport.zOutFile);
233	229	}else{
234	230	socket_close();
235	231	}
236	232	transport.isOpen = 0;
237	233	}
		@@ -280,10 +276,11 @@
280	276	fclose(transport.pFile);
281	277	zCmd = mprintf("%$ http --in %$ --out %$ --ipaddr 127.0.0.1"
282	278	" %$ --localauth",
283	279	g.nameOfExe, transport.zOutFile, transport.zInFile, pUrlData->name
284	280	);
	281	+ if( g.fHttpTrace ) fossil_print("RUN %s\n", zCmd);
285	282	fossil_system(zCmd);
286	283	free(zCmd);
287	284	transport.pFile = fossil_fopen(transport.zInFile, "rb");
288	285	}
289	286	}
290	287

	--- src/http_transport.c
	+++ src/http_transport.c
	@@ -141,12 +141,12 @@
141	if( pUrlData->path && pUrlData->path[0] ){
142	blob_append_escaped_arg(&zCmd, pUrlData->path, 1);
143	}else{
144	fossil_fatal("ssh:// URI does not specify a path to the repository");
145	}
146	if( g.fSshTrace ){
147	fossil_print("%s\n", blob_str(&zCmd)); /* Show the whole SSH command */
148	}
149	popen2(blob_str(&zCmd), &sshIn, &sshOut, &sshPid, 0);
150	if( sshPid==0 ){
151	socket_set_errmsg("cannot start ssh tunnel using [%b]", &zCmd);
152	}
	@@ -177,19 +177,15 @@
177	#else
178	socket_set_errmsg("HTTPS: Fossil has been compiled without SSL support");
179	rc = 1;
180	#endif
181	}else if( pUrlData->isFile ){
182	sqlite3_uint64 iRandId;
183	if( !db_looks_like_a_repository(pUrlData->name) ){
184	fossil_fatal("not a fossil repository: \"%s\"", pUrlData->name);
185	}
186	sqlite3_randomness(sizeof(iRandId), &iRandId);
187	transport.zOutFile = mprintf("%s-%llu-out.http",
188	g.zRepositoryName, iRandId);
189	transport.zInFile = mprintf("%s-%llu-in.http",
190	g.zRepositoryName, iRandId);
191	transport.pFile = fossil_fopen(transport.zOutFile, "wb");
192	if( transport.pFile==0 ){
193	fossil_fatal("cannot output temporary file: %s", transport.zOutFile);
194	}
195	transport.isOpen = 1;
	@@ -226,12 +222,12 @@
226	fclose(transport.pFile);
227	transport.pFile = 0;
228	}
229	file_delete(transport.zInFile);
230	file_delete(transport.zOutFile);
231	free(transport.zInFile);
232	free(transport.zOutFile);
233	}else{
234	socket_close();
235	}
236	transport.isOpen = 0;
237	}
	@@ -280,10 +276,11 @@
280	fclose(transport.pFile);
281	zCmd = mprintf("%$ http --in %$ --out %$ --ipaddr 127.0.0.1"
282	" %$ --localauth",
283	g.nameOfExe, transport.zOutFile, transport.zInFile, pUrlData->name
284	);

285	fossil_system(zCmd);
286	free(zCmd);
287	transport.pFile = fossil_fopen(transport.zInFile, "rb");
288	}
289	}
290

	--- src/http_transport.c
	+++ src/http_transport.c
	@@ -141,12 +141,12 @@
141	if( pUrlData->path && pUrlData->path[0] ){
142	blob_append_escaped_arg(&zCmd, pUrlData->path, 1);
143	}else{
144	fossil_fatal("ssh:// URI does not specify a path to the repository");
145	}
146	if( g.fSshTrace \|\| g.fHttpTrace ){
147	fossil_print("RUN %s\n", blob_str(&zCmd)); /* Show the whole SSH command */
148	}
149	popen2(blob_str(&zCmd), &sshIn, &sshOut, &sshPid, 0);
150	if( sshPid==0 ){
151	socket_set_errmsg("cannot start ssh tunnel using [%b]", &zCmd);
152	}
	@@ -177,19 +177,15 @@
177	#else
178	socket_set_errmsg("HTTPS: Fossil has been compiled without SSL support");
179	rc = 1;
180	#endif
181	}else if( pUrlData->isFile ){

182	if( !db_looks_like_a_repository(pUrlData->name) ){
183	fossil_fatal("not a fossil repository: \"%s\"", pUrlData->name);
184	}
185	transport.zOutFile = fossil_temp_filename();
186	transport.zInFile = fossil_temp_filename();



187	transport.pFile = fossil_fopen(transport.zOutFile, "wb");
188	if( transport.pFile==0 ){
189	fossil_fatal("cannot output temporary file: %s", transport.zOutFile);
190	}
191	transport.isOpen = 1;
	@@ -226,12 +222,12 @@
222	fclose(transport.pFile);
223	transport.pFile = 0;
224	}
225	file_delete(transport.zInFile);
226	file_delete(transport.zOutFile);
227	sqlite3_free(transport.zInFile);
228	sqlite3_free(transport.zOutFile);
229	}else{
230	socket_close();
231	}
232	transport.isOpen = 0;
233	}
	@@ -280,10 +276,11 @@
276	fclose(transport.pFile);
277	zCmd = mprintf("%$ http --in %$ --out %$ --ipaddr 127.0.0.1"
278	" %$ --localauth",
279	g.nameOfExe, transport.zOutFile, transport.zInFile, pUrlData->name
280	);
281	if( g.fHttpTrace ) fossil_print("RUN %s\n", zCmd);
282	fossil_system(zCmd);
283	free(zCmd);
284	transport.pFile = fossil_fopen(transport.zInFile, "rb");
285	}
286	}
287

M src/sync.c

+12 -1

		--- src/sync.c
		+++ src/sync.c
		@@ -238,11 +238,11 @@
238	238	&& find_option("share-links",0,0)!=0
239	239	){
240	240	*pSyncFlags \|= SYNC_SHARE_LINKS;
241	241	}
242	242
243		- /* Undocumented option: --transport-command COMMAND
	243	+ /* Option: --transport-command COMMAND
244	244	**
245	245	** Causes COMMAND to be run with three arguments in order to talk
246	246	** to the server.
247	247	**
248	248	** COMMAND URL PAYLOAD REPLY
		@@ -249,10 +249,15 @@
249	249	**
250	250	** URL is the server name. PAYLOAD is the name of a temporary file
251	251	** that will contain the xfer-protocol payload to send to the server.
252	252	** REPLY is a temporary filename in which COMMAND should write the
253	253	** content of the reply from the server.
	254	+ **
	255	+ ** CMD is reponsible for HTTP redirects. The following Fossil command
	256	+ ** can be used for CMD to achieve a working sync:
	257	+ **
	258	+ ** fossil test-httpmsg --xfer
254	259	*/
255	260	g.zHttpCmd = find_option("transport-command",0,1);
256	261
257	262	url_proxy_options();
258	263	clone_ssh_find_options();
		@@ -317,10 +322,12 @@
317	322	** --proxy PROXY Use the specified HTTP proxy
318	323	** -R\|--repository REPO Local repository to pull into
319	324	** --share-links Share links to mirror repos
320	325	** --ssl-identity FILE Local SSL credentials, if requested by remote
321	326	** --ssh-command SSH Use SSH as the "ssh" command
	327	+** --transport-command CMD Use external command CMD to move messages
	328	+** between client and server
322	329	** -v\|--verbose Additional (debugging) output
323	330	** --verily Exchange extra information with the remote
324	331	** to ensure no content is overlooked
325	332	**
326	333	** See also: [[clone]], [[config]], [[push]], [[remote]], [[sync]]
		@@ -368,10 +375,12 @@
368	375	** --proxy PROXY Use the specified HTTP proxy
369	376	** --private Push private branches too
370	377	** -R\|--repository REPO Local repository to push from
371	378	** --ssl-identity FILE Local SSL credentials, if requested by remote
372	379	** --ssh-command SSH Use SSH as the "ssh" command
	380	+** --transport-command CMD Use external command CMD to communicate with
	381	+** the server
373	382	** -v\|--verbose Additional (debugging) output
374	383	** --verily Exchange extra information with the remote
375	384	** to ensure no content is overlooked
376	385	**
377	386	** See also: [[clone]], [[config]], [[pull]], [[remote]], [[sync]]
		@@ -416,10 +425,12 @@
416	425	** --private Sync private branches too
417	426	** -R\|--repository REPO Local repository to sync with
418	427	** --share-links Share links to mirror repos
419	428	** --ssl-identity FILE Local SSL credentials, if requested by remote
420	429	** --ssh-command SSH Use SSH as the "ssh" command
	430	+** --transport-command CMD Use external command CMD to move message
	431	+** between the client and the server
421	432	** -u\|--unversioned Also sync unversioned content
422	433	** -v\|--verbose Additional (debugging) output
423	434	** --verily Exchange extra information with the remote
424	435	** to ensure no content is overlooked
425	436	**
426	437

	--- src/sync.c
	+++ src/sync.c
	@@ -238,11 +238,11 @@
238	&& find_option("share-links",0,0)!=0
239	){
240	*pSyncFlags \|= SYNC_SHARE_LINKS;
241	}
242
243	/* Undocumented option: --transport-command COMMAND
244	**
245	** Causes COMMAND to be run with three arguments in order to talk
246	** to the server.
247	**
248	** COMMAND URL PAYLOAD REPLY
	@@ -249,10 +249,15 @@
249	**
250	** URL is the server name. PAYLOAD is the name of a temporary file
251	** that will contain the xfer-protocol payload to send to the server.
252	** REPLY is a temporary filename in which COMMAND should write the
253	** content of the reply from the server.





254	*/
255	g.zHttpCmd = find_option("transport-command",0,1);
256
257	url_proxy_options();
258	clone_ssh_find_options();
	@@ -317,10 +322,12 @@
317	** --proxy PROXY Use the specified HTTP proxy
318	** -R\|--repository REPO Local repository to pull into
319	** --share-links Share links to mirror repos
320	** --ssl-identity FILE Local SSL credentials, if requested by remote
321	** --ssh-command SSH Use SSH as the "ssh" command


322	** -v\|--verbose Additional (debugging) output
323	** --verily Exchange extra information with the remote
324	** to ensure no content is overlooked
325	**
326	** See also: [[clone]], [[config]], [[push]], [[remote]], [[sync]]
	@@ -368,10 +375,12 @@
368	** --proxy PROXY Use the specified HTTP proxy
369	** --private Push private branches too
370	** -R\|--repository REPO Local repository to push from
371	** --ssl-identity FILE Local SSL credentials, if requested by remote
372	** --ssh-command SSH Use SSH as the "ssh" command


373	** -v\|--verbose Additional (debugging) output
374	** --verily Exchange extra information with the remote
375	** to ensure no content is overlooked
376	**
377	** See also: [[clone]], [[config]], [[pull]], [[remote]], [[sync]]
	@@ -416,10 +425,12 @@
416	** --private Sync private branches too
417	** -R\|--repository REPO Local repository to sync with
418	** --share-links Share links to mirror repos
419	** --ssl-identity FILE Local SSL credentials, if requested by remote
420	** --ssh-command SSH Use SSH as the "ssh" command


421	** -u\|--unversioned Also sync unversioned content
422	** -v\|--verbose Additional (debugging) output
423	** --verily Exchange extra information with the remote
424	** to ensure no content is overlooked
425	**
426

	--- src/sync.c
	+++ src/sync.c
	@@ -238,11 +238,11 @@
238	&& find_option("share-links",0,0)!=0
239	){
240	*pSyncFlags \|= SYNC_SHARE_LINKS;
241	}
242
243	/* Option: --transport-command COMMAND
244	**
245	** Causes COMMAND to be run with three arguments in order to talk
246	** to the server.
247	**
248	** COMMAND URL PAYLOAD REPLY
	@@ -249,10 +249,15 @@
249	**
250	** URL is the server name. PAYLOAD is the name of a temporary file
251	** that will contain the xfer-protocol payload to send to the server.
252	** REPLY is a temporary filename in which COMMAND should write the
253	** content of the reply from the server.
254	**
255	** CMD is reponsible for HTTP redirects. The following Fossil command
256	** can be used for CMD to achieve a working sync:
257	**
258	** fossil test-httpmsg --xfer
259	*/
260	g.zHttpCmd = find_option("transport-command",0,1);
261
262	url_proxy_options();
263	clone_ssh_find_options();
	@@ -317,10 +322,12 @@
322	** --proxy PROXY Use the specified HTTP proxy
323	** -R\|--repository REPO Local repository to pull into
324	** --share-links Share links to mirror repos
325	** --ssl-identity FILE Local SSL credentials, if requested by remote
326	** --ssh-command SSH Use SSH as the "ssh" command
327	** --transport-command CMD Use external command CMD to move messages
328	** between client and server
329	** -v\|--verbose Additional (debugging) output
330	** --verily Exchange extra information with the remote
331	** to ensure no content is overlooked
332	**
333	** See also: [[clone]], [[config]], [[push]], [[remote]], [[sync]]
	@@ -368,10 +375,12 @@
375	** --proxy PROXY Use the specified HTTP proxy
376	** --private Push private branches too
377	** -R\|--repository REPO Local repository to push from
378	** --ssl-identity FILE Local SSL credentials, if requested by remote
379	** --ssh-command SSH Use SSH as the "ssh" command
380	** --transport-command CMD Use external command CMD to communicate with
381	** the server
382	** -v\|--verbose Additional (debugging) output
383	** --verily Exchange extra information with the remote
384	** to ensure no content is overlooked
385	**
386	** See also: [[clone]], [[config]], [[pull]], [[remote]], [[sync]]
	@@ -416,10 +425,12 @@
425	** --private Sync private branches too
426	** -R\|--repository REPO Local repository to sync with
427	** --share-links Share links to mirror repos
428	** --ssl-identity FILE Local SSL credentials, if requested by remote
429	** --ssh-command SSH Use SSH as the "ssh" command
430	** --transport-command CMD Use external command CMD to move message
431	** between the client and the server
432	** -u\|--unversioned Also sync unversioned content
433	** -v\|--verbose Additional (debugging) output
434	** --verily Exchange extra information with the remote
435	** to ensure no content is overlooked
436	**
437

M www/sync.wiki

+60 -1

		--- www/sync.wiki
		+++ www/sync.wiki
		@@ -77,19 +77,42 @@
77	77	processor housed in a datacenter, nor does the client need to be a desktop
78	78	or handheld device. For the purposes of this article "client" simply means
79	79	the repository that initiates the conversation and "server" is the repository
80	80	that responds. Nothing more.</p>
81	81
82		-<h4>2.0.1 Encrypted Transport</h4>
	82	+<h4>2.0.1 HTTPS Transport</h4>
83	83
84	84	<p>In the current implementation of Fossil, the server only
85	85	understands HTTP requests. The client can send either
86	86	clear-text HTTP requests or encrypted HTTPS requests. But when
87	87	HTTPS requests are sent, they first must be decrypted by a web server
88	88	or proxy before being passed to the Fossil server. This limitation
89	89	may be relaxed in a future release.</p>
90	90
	91	+<h4>2.0.2 SSH Transport</h4>
	92	+
	93	+<p>When doing a sync using an "ssh:..." URL, the same HTTP transport protocol
	94	+is used. Fossil simply uses [https://en.wikipedia.org/wiki/Secure_Shell\|ssh]
	95	+to start an instance of the [/help?cmd=test-http\|fossil test-http] command
	96	+running on the remote machine. It then sends HTTP requests and gets back HTTP
	97	+replies over the SSH connection, rather than sending and receiving over an
	98	+internet socket. To see the specific "ssh" command that the Fossil client
	99	+runs in order to set up a connection, add either of the the "--httptrace" or
	100	+"--sshtrace" options to the "fossil sync" command line.
	101	+
	102	+<h4>2.0.3 FILE Transport</h4>
	103	+
	104	+<p>When doing a sync using a "file:..." URL, the same HTTP protocol is
	105	+still used. But instead of sending each HTTP request over a socket or
	106	+via SSH, the HTTP request is written into a temporary file. The client
	107	+then invokes the [/help?cmd=http\|fossil http] command in a subprocess
	108	+to process the request and and generate a reply. The client then reads
	109	+the HTTP reply out of a temporary file on disk, and deletes the two
	110	+temporary files. To see the specific "fossil http" command that is run
	111	+in order to implement the "file:" transport, add the "--httptrace"
	112	+option to the "fossil sync" command.
	113	+
91	114	<h3>2.1 Server Identification</h3>
92	115
93	116	<p>The server is identified by a URL argument that accompanies the
94	117	push, pull, or sync command on the client. (As a convenience to
95	118	users, the URL can be omitted on the client command and the same URL
		@@ -1005,5 +1028,41 @@
1005	1028	<li>Repositories keep track of all artifacts that are not named in any
1006	1029	cluster and send igot messages for those artifacts.
1007	1030	<li>Repositories keep track of all the phantoms they hold and send
1008	1031	gimme messages for those artifacts.
1009	1032	</ol>
	1033	+
	1034	+<h2>7.0 Troubleshooting And Debugging Hints</h2>
	1035	+
	1036	+<p>
	1037	+If you run the [/help?cmd=sync\|fossil sync] command
	1038	+(or [/help?cmd=pull\|pull] or [/help?cmd=push\|push] or
	1039	+[/help?cmd=clone\|clone]) with the --httptrace option, Fossil
	1040	+will keep a copy of each HTTP request and reply in files
	1041	+named:
	1042	+<ul>
	1043	+<li> <tt>http-request-</tt><i>N</i><tt>.txt</tt>
	1044	+<li> <tt>http-reply-</tt><i>N</i><tt>.txt</tt>
	1045	+</ul>
	1046	+
	1047	+<p>In the above, <i>N</i> is a integer that increments with each
	1048	+round-trip. If you are having trouble on the server side,
	1049	+you can run the "[/help?cmd=test-http\|fossil test-http]" command in a
	1050	+debugger using one the "http-request-N.txt" files as input and
	1051	+single step through the processing performed by the server.
	1052	+
	1053	+<p>The "--transport-command CMD" option on [/help?cmd=sync\|fossil sync]
	1054	+(and similar) causes the external program "CMD" to be used to move
	1055	+the sync message to the server and retrieve the sync reply. The
	1056	+CMD is given three arguments:
	1057	+<ol>
	1058	+<li> The URL of the server
	1059	+<li> The name of a temporary file that contains the output-bound sync
	1060	+ protocol text, with the HTTP headers
	1061	+<li> The name of a temporary file into which the CMD should write the
	1062	+ reply sync protocol text, again without any HTTP headers
	1063	+</ol>
	1064	+
	1065	+<p>In a complex debugging situation, you can run the command
	1066	+"fossil sync --transport-command ./debugging_script" where
	1067	+"debugging_script" is some script of your own that invokes
	1068	+the anomolous behavior your are trying to debug.
1010	1069

	--- www/sync.wiki
	+++ www/sync.wiki
	@@ -77,19 +77,42 @@
77	processor housed in a datacenter, nor does the client need to be a desktop
78	or handheld device. For the purposes of this article "client" simply means
79	the repository that initiates the conversation and "server" is the repository
80	that responds. Nothing more.</p>
81
82	<h4>2.0.1 Encrypted Transport</h4>
83
84	<p>In the current implementation of Fossil, the server only
85	understands HTTP requests. The client can send either
86	clear-text HTTP requests or encrypted HTTPS requests. But when
87	HTTPS requests are sent, they first must be decrypted by a web server
88	or proxy before being passed to the Fossil server. This limitation
89	may be relaxed in a future release.</p>
90























91	<h3>2.1 Server Identification</h3>
92
93	<p>The server is identified by a URL argument that accompanies the
94	push, pull, or sync command on the client. (As a convenience to
95	users, the URL can be omitted on the client command and the same URL
	@@ -1005,5 +1028,41 @@
1005	<li>Repositories keep track of all artifacts that are not named in any
1006	cluster and send igot messages for those artifacts.
1007	<li>Repositories keep track of all the phantoms they hold and send
1008	gimme messages for those artifacts.
1009	</ol>




































1010

	--- www/sync.wiki
	+++ www/sync.wiki
	@@ -77,19 +77,42 @@
77	processor housed in a datacenter, nor does the client need to be a desktop
78	or handheld device. For the purposes of this article "client" simply means
79	the repository that initiates the conversation and "server" is the repository
80	that responds. Nothing more.</p>
81
82	<h4>2.0.1 HTTPS Transport</h4>
83
84	<p>In the current implementation of Fossil, the server only
85	understands HTTP requests. The client can send either
86	clear-text HTTP requests or encrypted HTTPS requests. But when
87	HTTPS requests are sent, they first must be decrypted by a web server
88	or proxy before being passed to the Fossil server. This limitation
89	may be relaxed in a future release.</p>
90
91	<h4>2.0.2 SSH Transport</h4>
92
93	<p>When doing a sync using an "ssh:..." URL, the same HTTP transport protocol
94	is used. Fossil simply uses [https://en.wikipedia.org/wiki/Secure_Shell\|ssh]
95	to start an instance of the [/help?cmd=test-http\|fossil test-http] command
96	running on the remote machine. It then sends HTTP requests and gets back HTTP
97	replies over the SSH connection, rather than sending and receiving over an
98	internet socket. To see the specific "ssh" command that the Fossil client
99	runs in order to set up a connection, add either of the the "--httptrace" or
100	"--sshtrace" options to the "fossil sync" command line.
101
102	<h4>2.0.3 FILE Transport</h4>
103
104	<p>When doing a sync using a "file:..." URL, the same HTTP protocol is
105	still used. But instead of sending each HTTP request over a socket or
106	via SSH, the HTTP request is written into a temporary file. The client
107	then invokes the [/help?cmd=http\|fossil http] command in a subprocess
108	to process the request and and generate a reply. The client then reads
109	the HTTP reply out of a temporary file on disk, and deletes the two
110	temporary files. To see the specific "fossil http" command that is run
111	in order to implement the "file:" transport, add the "--httptrace"
112	option to the "fossil sync" command.
113
114	<h3>2.1 Server Identification</h3>
115
116	<p>The server is identified by a URL argument that accompanies the
117	push, pull, or sync command on the client. (As a convenience to
118	users, the URL can be omitted on the client command and the same URL
	@@ -1005,5 +1028,41 @@
1028	<li>Repositories keep track of all artifacts that are not named in any
1029	cluster and send igot messages for those artifacts.
1030	<li>Repositories keep track of all the phantoms they hold and send
1031	gimme messages for those artifacts.
1032	</ol>
1033
1034	<h2>7.0 Troubleshooting And Debugging Hints</h2>
1035
1036	<p>
1037	If you run the [/help?cmd=sync\|fossil sync] command
1038	(or [/help?cmd=pull\|pull] or [/help?cmd=push\|push] or
1039	[/help?cmd=clone\|clone]) with the --httptrace option, Fossil
1040	will keep a copy of each HTTP request and reply in files
1041	named:
1042	<ul>
1043	<li> <tt>http-request-</tt><i>N</i><tt>.txt</tt>
1044	<li> <tt>http-reply-</tt><i>N</i><tt>.txt</tt>
1045	</ul>
1046
1047	<p>In the above, <i>N</i> is a integer that increments with each
1048	round-trip. If you are having trouble on the server side,
1049	you can run the "[/help?cmd=test-http\|fossil test-http]" command in a
1050	debugger using one the "http-request-N.txt" files as input and
1051	single step through the processing performed by the server.
1052
1053	<p>The "--transport-command CMD" option on [/help?cmd=sync\|fossil sync]
1054	(and similar) causes the external program "CMD" to be used to move
1055	the sync message to the server and retrieve the sync reply. The
1056	CMD is given three arguments:
1057	<ol>
1058	<li> The URL of the server
1059	<li> The name of a temporary file that contains the output-bound sync
1060	protocol text, with the HTTP headers
1061	<li> The name of a temporary file into which the CMD should write the
1062	reply sync protocol text, again without any HTTP headers
1063	</ol>
1064
1065	<p>In a complex debugging situation, you can run the command
1066	"fossil sync --transport-command ./debugging_script" where
1067	"debugging_script" is some script of your own that invokes
1068	the anomolous behavior your are trying to debug.
1069

Fossil SCM

Keyboard Shortcuts