document writefile symlink checks

[ikiwiki.git] / doc / plugins / write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 99eea3d1696b3240647b439edae4d8768ddf1033..1a119b99b679498c5188620a56e9d7fce81c5bc6 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -629,6 +629,16 @@ A failure to write the file will result in it dying with an error.
 
 If the destination directory doesn't exist, it will first be created.
 
 
 If the destination directory doesn't exist, it will first be created.
 

+The filename and directory are separate parameters because of
+some security checks done to avoid symlink attacks. Before writing a file,
+it checks to make sure there's not a symlink with its name, to avoid
+following the symlink. If the filename parameter includes a subdirectory
+to put the file in, it also checks if that subdirectory is a symlink, etc.
+The directory parameter, however, is not checked for symlinks. So,
+generally the directory parameter is a trusted toplevel directory like
+the srcdir or destdir, and any subdirectories of this are included in the
+filename parameter.
+

 #### `will_render($$)`
 
 Given a page name and a destination file name (not including the base
 #### `will_render($$)`
 
 Given a page name and a destination file name (not including the base