2 FIles transferred over SHell protocol (V 0.0.3)
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 This protocol was designed for transferring files over a remote shell
6 connection (rsh and compatibles). It can be as well used for transfers over
7 rsh, and there may be other uses.
9 Client sends requests of following form:
12 equivalent shell commands,
13 which may be multiline
15 Only fish commands are defined here, shell equivalents are for your
16 information only and will probably vary from implementation to
17 implementation. Fish commands always have priority: server is
18 expected to execute fish command if it understands it. If it does not,
19 however, it can try the luck and execute shell command.
21 Since version 4.7.3, the scripts that FISH sends to host machines after
22 a command is transmitted are no longer hardwired in the Midnight
23 Commander source code.
25 First, mc looks for system-wide set of scripts, then it checks whether
26 current user has host-specific overrides in his per-user mc
27 configuration folder. User-defined overrides take priority over
28 sytem-wide scripts if they exist. The order in which the folders are
29 traversed is as follows:
32 ~/.mc/fish/<hostname>/
34 Server's reply is multiline, but always ends with
36 ### 000<optional text>
38 line. ### is prefix to mark this line, 000 is return code. Return
39 codes are superset to those used in ftp.
41 There are few new exit codes defined:
43 000 don't know; if there were no previous lines, this marks COMPLETE
44 success, if they were, it marks failure.
46 001 don't know; if there were no previous lines, this marks
47 PRELIMinary success, if they were, it marks failure
51 Client uses "echo FISH:;/bin/sh" as command executed on remote
52 machine. This should make it possible for server to distinguish FISH
53 connections from normal rsh/ssh.
58 echo; start_fish_server; echo '### 200'
60 This command is sent at the beginning. It marks that client wishes to
61 talk via FISH protocol. #VER command must follow. If server
62 understands FISH protocol, it has option to put FISH server somewhere
63 on system path and name it start_fish_server.
65 #VER 0.0.2 <feature1> <feature2> <...>
68 This command is the second one. It sends client version and extensions
69 to the server. Server should reply with protocol version to be used,
70 and list of extensions accepted.
78 Server should reply with current directory (in form /abc/def/ghi)
79 followed by line indicating success.
82 ls -lLa $1 | grep '^[^cbt]' | ( while read p x u g s m d y n; do echo "P$p $u.$g
87 ls -lLa $1 | grep '^[cb]' | ( while read p x u g a i m d y n; do echo "P$p $u.$g
94 This allows client to list directory or get status information about
95 single file. Output is in following form (any line except :<filename>
98 P<unix permissions> <owner>.<group>
100 d<3-letters month name> <day> <year or HH:MM>
101 D<year> <month> <day> <hour> <minute> <second>[.1234]
102 E<major-of-device>,<minor>
104 L<filename symlink points to>
105 <blank line to separate items>
107 Unix permissions are of form X--------- where X is type of
108 file. Currently, '-' means regular file, 'd' means directory, 'c', 'b'
109 means character and block device, 'l' means symbolic link, 'p' means
110 FIFO and 's' means socket.
112 'd' has three fields: month (one of strings Jan Feb Mar Apr May Jun
113 Jul Aug Sep Oct Nov Dec), day of month, and third is either single
114 number indicating year, or HH:MM field (assume current year in such
115 case). As you've probably noticed, this is pretty broken; it is for
116 compatibility with ls listing.
119 ls -l /some/name | ( read a b c d x e; echo $x ); echo '### 100'; cat /some/name; echo '### 200'
121 Server sends line with filesize on it, followed by line with ### 100
122 indicating partial success, then it sends binary data (exactly
123 filesize bytes) and follows them with (with no preceding newline) ###
126 Note that there's no way to abort running RETR command - except
127 closing the connection.
129 #STOR <size> /file/name
130 > /file/name; echo '### 001'; ( dd bs=4096 count=<size/4096>; dd bs=<size%4096> count=1 ) 2>/dev/null | ( cat > %s; cat > /dev/null ); echo '### 200'
132 This command is for storing /file/name, which is exactly size bytes
133 big. You probably think I went crazy. Well, I did not: that strange
134 cat > /dev/null has purpose to discard any extra data which was not
135 written to disk (due to for example out of space condition).
137 [Why? Imagine uploading file with "rm -rf /" line in it.]
140 cd /somewhere; echo '### 000'
142 It is specified here, but I'm not sure how wise idea is to use this
143 one: it breaks stateless-ness of the protocol.
145 Following commands should be rather self-explanatory:
148 chmod 1234 file; echo '### 000'
151 rm -f /some/path; echo '### 000'
154 mkdir /some/path; echo '### 000'
157 rmdir /some/path; echo '### 000'
159 #RENAME /path/a /path/b
160 mv /path/a /path/b; echo '### 000'
162 #LINK /path/a /path/b
163 ln /path/a /path/b; echo '### 000'
165 #SYMLINK /path/a /path/b
166 ln -s /path/a /path/b; echo '### 000'
168 #CHOWN user /file/name
169 chown user /file/name; echo '### 000'
171 #CHGRP group /file/name
172 chgrp group /file/name; echo '### 000'
175 ...collect info about host into $result ...
179 #READ <offset> <size> /path/and/filename
180 cat /path/and/filename | ( dd bs=4096 count=<offset/4096> > /dev/null;
181 dd bs=<offset%4096> count=1 > /dev/null;
182 dd bs=4096 count=<offset/4096>;
183 dd bs=<offset%4096> count=1; )
185 Returns ### 200 on successful exit, ### 291 on successful exit when
186 reading ended at eof, ### 292 on successfull exit when reading did not
189 #WRITE <offset> <size> /path/and/filename
191 Hmm, shall we define these ones if we know our client is not going to
194 you can use follow parameters:
204 'FISH_FILESIZE' used if we operate with single file name in 'unlink', 'rmdir', 'chmod', etc...
205 'FISH_FILEFROM','FISH_FILETO' used if we operate with two files in 'ln', 'hardlink', 'mv' etc...
206 'FISH_FILEOWNER', 'FISH_FILEGROUPE' is a new user/group in chown