*SudoEdit.txt* Edit Files using Sudo/su Author: Christian Brabandt Version: Vers 0.19 Wed, 14 Aug 2013 22:29:27 +0200 Copyright: (c) 2009-2013 by Christian Brabandt *SudoEdit-copyright* The VIM LICENSE applies to SudoEdit.vim and SudoEdit.txt (see |copyright|) except use SudoEdit instead of "Vim". NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK. ============================================================================== 1. Contents *SudoEdit* *SudoEdit-contents* 1. Contents......................................: |SudoEdit-contents| 2. SudoEdit Manual...............................: |SudoEdit-manual| 1 SudoEdit: SudoRead............................: |SudoRead| 2 SudoEdit: SudoWrite...........................: |SudoWrite| 3. SudoEdit Configuration........................: |SudoEdit-config| 1 SudoEdit on Windows...........................: |SudoEdit-Win| 4. SudoEdit Debugging............................: |SudoEdit-debug| 5. SudoEdit F.A.Q................................: |SudoEdit-faq| 6. SudoEdit History..............................: |SudoEdit-history| ============================================================================== 2. SudoEdit Manual *SudoEdit-manual* Functionality This plugin enables vim to read files, using sudo or su or any other tool that can be used for changing the authentication of a user. Therefore it needs any of sudo or su installed and usable by the user. This means, you have to know the credentials to authenticate yourself as somebody else. That's why this plugin probably won't work on Windows, but you might be able to configure it to use a method that works on Windows (see |SudoEdit-config|) By default SudoEdit will first try to use sudo and if sudo is not found it will fall back and try to use su. Note, that you might have to configure these tools, before they can use them successfully. SudoEdit requires at least a Vim Version 7 with patch 111 installed. Patch 111 introduced the |shellescape()| functionality. On a Mac (using MacVim), it uses the command "security execute-with-privileges" to query for your password, on Unix, it can make use of graphical password dialog tools like ssh-gnome-askpass (see |g:sudo_askpass|) The SudoEdit Plugin provides 2 Commands: ============================================================================== 2.1 SudoRead *SudoRead* :SudoRead[!] [file] SudoRead will read the given file name using any of the configured methods for superuser authtication. It basically does something like this: > :r !sudo cat file If no filename is given, SudoRead will try to reread the current file name. If the current buffer does not contain any file, it will abort. If the ! argument is used, the current buffer contents will be discarded, if it was modified. SudoRead provides file completion, so you can use on the commandline to specify the file to read. For compatibility with the old sudo.vim Plugin, SudoEdit.vim also supports reading and writing using the protocol sudo: So instead of using :SudoRead /etc/fstab you can also use :e sudo:/etc/fstab (which does not provide filename completion) ============================================================================== 2.2 SudoWrite *SudoWrite* :[range]SudoWrite[!] [file] SudoWrite will write the given file using any of the configured methods for superuser authtication. It basically does something like this: > :w !sudo tee >/dev/null file If no filename is given, SudoWrite will try to write the current file name. If the current buffer does not contain any file, it will abort. You can specify a range to write just like |:w|. If no range is given, it will write the whole file. If the bang argument is not given, the buffer will only be written, if it was modified. Again, you can use the protocol handler sudo: for writing. ============================================================================== 3. SudoEdit Configuration *SudoEdit-config* By default SudoEdit will try to use sudo and if it is not found, it will try to use su. Just because SudoEdit finds either sudo or su installed, does not mean, that you can already use it. You might have to configure it and of course you need to have the credentials for super-user access. *g:sudoAuth* The tool to use for authentication is can be changed by setting the variable g:sudoAuth. If this variable exists, SudoEdit will first try to use the specified tool before falling back to either sudo or su (in that order). For example, you could use ssh to use as authentication tool by setting g:sudoAuth in your .vimrc as follows: > let g:sudoAuth="ssh" < *g:sudoAuthArg* The variable g:sudoAuthArg specifies how to use the given authentication tool. You can specify additional parameters that will be used. You could for example also define here which user to change to. By default, SudoEdit will try to become the superuser e.g. root. If you want to use ssh as authentication facility, you can set g:sudoAuthArg as follows in your .vimrc: > let g:sudoAuthArg="root@localhost" For su, you would use g:sudoAuthArg="-c", but you do not have to set it, the plugin will automatically use -c if it detects, that su is used. *g:sudo_no_gui* *g:sudo_askpass* If the plugin uses sudo for authenticating and the plugin finds any of gnome-ssh-askpass, ksshaskpass or x11-ssh-askpass and a graphical Display connection is possible, the plugin uses the first of the tools it finds to display a graphical dialog, in which you can enter the password. If you like to specify a different tool, you can set the g:sudo_askpass variable to specify a different tool to use, e.g. > :let g:sudo_askpass='/usr/lib/openssh/gnome-ssh-askpass' to make use of gnome-ssh-askpass for querying the password. If you like to disable this, set the variable g:sudo_no_gui, e.g. > :let g:sudo_no_gui=1 ============================================================================== 3.1 SudoEdit on Windows *SudoEdit-Win* It should be possible to use SudoEdit on Windows using the runas command. The plugin should by default try to detect when it runs under Windows and either try to use runas or elevate. For this to work, those commands need to be in your %PATH% and be executable. For runas, SudoEdit tries to simply run the command like this: > runas /noprofile /user:Administrator "type file" while elevate would simply use: > elevate "type file" This has not yet been tested, but if you have successfully setup SudoEdit on Windows, please let me know, so that the procedure can be properly documented. Alternatively, it should be possible to setup SudoEdit to use the ShellRunAs, sudowin or the Surun command and configuring the plugin using the |g:sudoAuth| and |g:sudoAuthArg| variables. If you need to use a different administrator account for Windows, I suggest that you set the |g:sudoAuthArg| variable, e.g. setting: > :let g:sudoAuthArg = '/noprofile /user:\"AdminUser@MyDomain\"' to let SudoEdit use the AdminUser within the domain MyDomain for administrator access. For further help on this topic see those links: runas: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/runas.mspx sudowin: http://sourceforge.net/projects/sudowin/ elevate: http://technet.microsoft.com/en-us/magazine/2007.06.utilityspotlight.aspx ShellRunAs: http://technet.microsoft.com/en-us/sysinternals/cc300361.aspx Surun: http://kay-bruns.de/wp/software/surun/ Alternatively, on recent Windows versions, you can use the builtin UAC system and have a batch script automatically elevated, which will do the writing and reading of the file. This method is rather experimental and might not work in all cases. To make use of UAC set the g:sudoAuth variable to the string "uac": > :let g:sudoAuth="uac" ============================================================================== 4. SudoEdit Debugging *SudoEdit-debug* You can debug this plugin and the shell code that will be executed by setting: > let g:sudoDebug=1 This ensures, that debug messages will be appended to the |message-history|. ============================================================================== 5. SudoEdit F.A.Q. *SudoEdit-faq* 1) This plugin isn't working, while executing the same commands on the shell works fine using sudo. Make sure, that requiretty is not set. If it is set, you won't be able to use sudo from within vim. 2) Vim is frozen! Vim is probably waiting for the password but not redrawing correctly. You should be able to enter your passphrase followed by Enter blindly and Vim should respond again. In this case, try, if setting the g:sudoDebug variable in your .vimrc helps > :let g:sudoDebug = 1 That should make the plugin output some more information and you should be able to see the password prompt. 3) The plugin is still not working! Write me an email (look in the first line for my mail address), append the debug messages and tell me what exactly is not working. I will look into it and if there is a bug fix this plugin. 4) The plugin does not create undo-files. What's wrong? It is not directly possible to create undofiles in write-protected directories, therefore, when your 'undodir' setting contains '.' (the default), the plugin won't simply write the undofile. If you want undofiles to work, set the 'undodir' option to a directory, that is writable. 5) Great work! Write me an email (look in the first line for my mail address). And if you are really happy, vote for the plugin and consider looking at my Amazon whishlist: http://www.amazon.de/wishlist/2BKAHE8J7Z6UW 6) Plugin Feedback *SudoEdit-feedback* Feedback is always welcome. If you like the plugin, please rate it at the vim-page: http://www.vim.org/scripts/script.php?script_id=2709 You can also follow the development of the plugin at github: http://github.com/chrisbra/SudoEdit.vim Please don't hesitate to report any bugs to the maintainer, mentioned in the third line of this document. ============================================================================== 6. SudoEdit History *SudoEdit-history* 0.19: Aug 14, 2013 "{{{1 - |SudoWrite| should always write if a filename has been given (issue #23, reported by Daniel Hahler, thanks!) - Better filename completion for |SudoWrite| and |SudoRead| commands (issue #20 reported by Daniel Hahler, thanks!) - Fix error in VimLeave autocommand (issue #22, reported by Daniel Hahler, thanks!) - reset 'shell' value (issue #24, reported by Raghavendra Prabhu, thanks!) 0.18: Feb 16, 2013 "{{{1 - expand() may return empty filenames (issue #17 patch by Daniel Hahler, thanks!) - better exception handling (issue #19) - included sudo.cmd for better usage on Windows - enable sudo.cmd to use UAC optionally 0.17: Aug 20, 2012 "{{{1 - Guard against a vim without persistent_undo feature - fix variable typo (https://github.com/chrisbra/SudoEdit.vim/pull/16 patch by NagatoPain, thanks!) 0.16: May 17, 2012 "{{{1 - Make the plugin usable on Windows |SudoEdit-Win| 0.15: May 08, 2012 "{{{1 - fix Syntax error (reported by Gary Johnson, thanks!) 0.14: Apr 30, 2012 "{{{1 - fix issue #15 (https://github.com/chrisbra/SudoEdit.vim/issues/15 reported by Lenin Lee, thanks!) 0.13: Apr 28, 2012 "{{{1 - in graphical Vim, display messages, so one knows, that one needs to enter the password (reported by Rob Shinn, thanks!) - Allow bang attribute to |SudoRead| and |SudoWrite| - Make use of graphical dialogs for sudo to read the passwords, if possible - Better debugging - Code cleanup - better filename completion with :SudoRead/SudoWrite (now also supports completing sudo: protocol handler) 0.12: Jan 31, 2012 "{{{1 - Avoid redraw when changing permissions of the undofile - Don't move cursor on Reading/Writing (issue https://github.com/chrisbra/SudoEdit.vim/issues/11, reported by Daniel Hahler, Thanks!) - Support for calling Netrw with another userid/password (issue https://github.com/chrisbra/SudoEdit.vim/issues/4, reported by Daniel Hahler, Thanks!) - Autocmds for Writing did not fire (issue https://github.com/chrisbra/SudoEdit.vim/issues/10, partly by Raghavendra D Prabhu, Thanks!) - Newly created files are not set 'nomodified' (issue https://github.com/chrisbra/SudoEdit.vim/issues/12, reported by Daniel Hahler, Thanks!) - Can't create undofiles in write-protected directories (issue https://github.com/chrisbra/SudoEdit.vim/issues/14, reported by Matias Kangasjärvelä, Thanks!) 0.11: Dec 15, 2011 "{{{1 -change owner of undofile to that of the edited super-user file, so vim will automatically load the undofile when opening that file the next time (reported by Sean Farley and blueyed, thanks!) -Only set the filename using :f when writing to another file (https://github.com/chrisbra/SudoEdit.vim/pull/8 and also https://github.com/chrisbra/SudoEdit.vim/issues/5 patch by Daniel Hahler, thanks!) -fix https://github.com/chrisbra/SudoEdit.vim/issues/6 (fix permissions and path of the undofile, partly by Daniel Hahler, thanks!) -Don't reread the file and write undofiles for empty files (https://github.com/chrisbra/SudoEdit.vim/issues/7 reported by Daniel Hahler, thanks!) 0.10: Nov 18, 2011 "{{{1 -fix https://github.com/chrisbra/SudoEdit.vim/issues/1 (exception "emptyfile" not caught, reported by Daniel Hahler, thanks!) -fix https://github.com/chrisbra/SudoEdit.vim/issues/2 (Avoid W13 error, reported by Daniel Hahler, thanks!) -fix https://github.com/chrisbra/SudoEdit.vim/issues/3 (Write undofiles, reported by Daniel Hahler, thanks!) 0.8: Apr 20, 2010 "{{{1 - Made plugin autoloadable so the code is only loaded, when necessary 0.7: Oct 26, 2009 "{{{1 - Support for reading/writing using sudo: protocol handler - Added Debugging capabilities 0.6: July 14, 2009 "{{{1 - Fix minor bug, that prevents setting the filename correctly when writing. 0.5: July 08, 2009 "{{{1 - Enables the plugin for |GetLatestVimScripts| 0.4: July 08, 2009 "{{{1 - First release - Added Documentation 0.3: July 07, 2009 "{{{1 - Internal version, added su support - Added configuration variables 0.2: July 07, 2009 "{{{1 - Internal version, Working sudo support - Created plugin 0.1: July 07, 2009 "{{{1 - Internal version, First working version, using simple commands ============================================================================== Modeline: "{{{1 vim:tw=78:ts=8:ft=help:fdm=marker:fdl=0:norl