1Overview of kio_fish 2==================== 3 4 FISH is a protocol to get filesystem access without special server 5 software, only using a remote shell. (Hence the name: FIles transferred 6 over SHell protocol). 7 It was first devised by Pavel Machek <pavel@bug.ucw.cz> and implemented 8 as a Midnight Commander vfs module in 1998. 9 10 This is a complete client implementation using his original version 11 0.0.2 protocol, extending it with 2 commands (which are only optional - 12 should a real FISH server exist on server side that doesn't understand 13 them, this ioslave still works, only slower). Moreover, this client does 14 complete shell metacharacter quoting on all arguments, a fact that is 15 neccessary but missing from the specs. 16 Extensions used are: append (APPEND command), copy (COPY command), 17 lscount (LIST first prints number of files to be listed), lslinks (LIST 18 shows symlink info instead of info about link targets), lsmime (LIST 19 determines the MIME type on the server side) 20 Password and host key queries are handled via dialog boxes. 21 The goal of this client is to make a remote directory look and feel exactly 22 like a local directory, with all comfort, only slower. 23 24 NOTE: From version 1.1.3 on, compression is no longer turned on auto- 25 matically. You have to specify it via ~/.ssh/config or wherever 26 your local ssh client reads its settings. The same goes for all other 27 connection parameters. OpenSSH for example has a powerful configuration 28 file syntax which lets you configure access differently for each host, 29 something I do not intend to duplicate. Read the ssh_config(5) man page 30 for details. If someone knows the docs to read for commercial ssh please 31 tell me so I can include that here as well. 32 33 Included below is the original posting from the mc mailing list archives. 34 35 If perl is installed on the remote machine and in the default PATH, it will 36 be used to transfer a custom server script which is much faster than 37 shell-only mode and more predictable as well. The script is stored in a 38 file called .fishsrv.pl in the working directory directly after login and 39 will be reused on subsequent connections. 40 41 2001/10/07 Jörg Walter <trouble@garni.ch> 42 43 44 45From: Pavel Machek <pavel@bug.ucw.cz> 46Subject: New virtual filesystem - fish 47Date: Tue, 15 Sep 1998 22:30:07 +0200 48 49Hi! 50 51New virtual filesystem has been created, which allows you to access 52files on remote computer over rsh/ssh connection, with _no_ server 53needed on the other side. To use it from mc or any program using 54libvfs.so, do 55 56cd /#sh:user@host.to.connect.to/ 57 58Note that password authentication will not work, so you must be 59authenticated using [rs]hosts or RSA key. 60 61For protocol, see mc/vfs/README.fish. If someone wants to write 62server, it would be good idea, since it works without server but 63performance is not optimal. 64 65 Pavel 66 67PS: Protocol looks like this. If you have any comments, it is time to 68speak. 69 70 71 FIles transferred over SHell protocol (V 0.0.2) 72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74This protocol was designed for transferring files over secureshell 75(ssh) connection. It can be as well used for transfers over rsh, and 76there may be other uses. 77 78Client sends requests of following form: 79 80#FISH_COMMAND 81equivalent shell commands, 82which may be multiline 83 84Only fish commands are defined here, shell equivalents are for your 85information only and will probably vary from implementation to 86implementation. Fish commands always have priority: server is 87expected to execute fish command if it understands it. If it does not, 88however, it can try the luck and execute shell command. 89 90Server's reply is multiline, but alwyas ends with 91 92### 000<optional text> 93 94line. ### is prefix to mark this line, 000 is return code. Return 95codes are superset to those used in ftp. 96 97There are few new exit codes defined: 98 99000 don't know; if there were no previous lines, this marks COMPLETE 100success, if they were, it marks failure. 101 102001 don't know; if there were no previous lines, this marks 103PRELIMinary success, if they were, it marks failure 104 105 Connecting 106 ~~~~~~~~~~ 107Client uses "echo FISH:;/bin/sh" as command executed on remote 108machine. This should make it possible for server to distinguish FISH 109connections from normal rsh/ssh. 110 111 Commands 112 ~~~~~~~~ 113#FISH 114echo; start_fish_server; echo '### 200' 115 116This command is sent at the begining. It marks that client wishes to 117talk via FISH protocol. #VER command must follow. If server 118understands FISH protocol, it has option to put FISH server somewhere 119on system path and name it start_fish_server. 120 121#VER 0.0.2 <feature1> <feature2> <...> 122echo '### 000' 123 124This command is the second one. It sends client version and extensions 125to the server. Server should reply with protocol version to be used, 126and list of extensions accepted. 127 128VER 0.0.0 <feature2> 129### 200 130 131#PWD 132pwd; echo '### 200' 133 134Server should reply with current directory (in form /abc/def/ghi) 135followed by line indicating success. 136 137#LIST /directory 138ls -lLa $1 | grep '^[^cbt]' | ( while read p x u g s m d y n; do echo "P$p $u.$g 139S$s 140d$m $d $y 141:$n 142"; done ) 143ls -lLa $1 | grep '^[cb]' | ( while read p x u g a i m d y n; do echo "P$p $u.$g 144E$a$i 145dD$m $d $y 146:$n 147"; done ) 148echo '### 200' 149 150This allows client to list directory or get status information about 151single file. Output is in following form (any line except :<filename> 152may be ommited): 153 154P<unix permissions> <owner>.<group> 155S<size> 156d<3-letters month name> <day> <year or HH:MM> 157D<year> <month> <day> <hour> <minute> <second>[.1234] 158E<major-of-device>,<minor> 159:<filename> 160L<filename symlink points to> 161<blank line to separate items> 162 163Unix permissions are of form X--------- where X is type of 164file. Currently, '-' means regular file, 'd' means directory, 'c', 'b' 165means character and block device, 'l' means symbolic link, 'p' means 166FIFO and 's' means socket. 167 168'd' has three fields: month (one of strings Jan Feb Mar Apr May Jun 169Jul Aug Sep Oct Nov Dec), day of month, and third is either single 170number indicating year, or HH:MM field (assume current year in such 171case). As you've probably noticed, this is pretty broken; it is for 172compatibility with ls listing. 173 174#RETR /some/name 175ls -l /some/name | ( read a b c d x e; echo $x ); echo '### 100'; cat /some/name; echo '### 200' 176 177Server sends line with filesize on it, followed by line with ### 100 178indicating partial success, then it sends binary data (exactly 179filesize bytes) and follows them with (with no preceeding newline) ### 180200. 181 182Note that there's no way to abort running RETR command - except 183closing the connection. 184 185#STOR <size> /file/name 186<i><font color="#008000">> /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' 187</font></i> 188This command is for storing /file/name, which is exactly size bytes 189big. You probably think I went crazy. Well, I did not: that strange 190cat > /dev/null has purpose to discard any extra data which was not 191written to disk (due to for example out of space condition). 192 193[Why? Imagine uploading file with "rm -rf /" line in it.] 194 195#CWD /somewhere 196cd /somewhere; echo '### 000' 197 198It is specified here, but I'm not sure how wise idea is to use this 199one: it breaks stateless-ness of the protocol. 200 201Following commands should be rather self-explanatory: 202 203#CHMOD 1234 file 204chmod 1234 file; echo '### 000' 205 206#DELE /some/path 207rm -f /some/path; echo '### 000' 208 209#MKD /some/path 210mkdir /some/path; echo '### 000' 211 212#RMD /some/path 213rmdir /some/path; echo '### 000' 214 215#RENAME /path/a /path/b 216mv /path/a /path/b; echo '### 000' 217 218#LINK /path/a /path/b 219ln /path/a /path/b; echo '### 000' 220 221#SYMLINK /path/a /path/b 222ln -s /path/a /path/b; echo '### 000' 223 224#CHOWN user /file/name 225chown user /file/name; echo '### 000' 226 227#CHGRP group /file/name 228chgrp group /file/name; echo '### 000' 229 230#READ <offset> <size> /path/and/filename 231cat /path/and/filename | ( dd bs=4096 count=<offset/4096> > /dev/null; 232dd bs=<offset%4096> count=1 > /dev/null; 233dd bs=4096 count=<offset/4096>; 234dd bs=<offset%4096> count=1; ) 235 236Returns ### 200 on successfull exit, ### 291 on successfull exit when 237reading ended at eof, ### 292 on successfull exit when reading did not 238end at eof. 239 240#WRITE <offset> <size> /path/and/filename 241 242Hmm, shall we define these ones if we know our client is not going to 243use them? 244 245 246That's all, folks! 247 pavel@ucw.cz 248 249 250-- 251I'm really pavel@atrey.karlin.mff.cuni.cz. Pavel 252Look at http://atrey.karlin.mff.cuni.cz/~pavel/ ;-). 253