1 // tawesoft.co.uk/go/drop 2 // 3 // Copyright © 2020 - 2021 Tawesoft Ltd <open-source@tawesoft.co.uk> 4 // Copyright © 2020 - 2021 Ben Golightly <ben@tawesoft.co.uk> 5 // 6 // Permission is hereby granted, free of charge, to any person obtaining a copy 7 // of this software and associated documentation files (the "Software"), to deal 8 // in the Software without restriction, including without limitation the rights 9 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 // copies of the Software, and to permit persons to whom the Software is 11 // furnished to do so, subject to the following conditions: 12 // 13 // The above copyright notice and this permission notice shall be included in all 14 // copies or substantial portions of the Software. 15 // 16 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 // SOFTWARE. 23 24 // Package drop implements the ability to start a process as root, open 25 // privileged resources as files, drop privileges to become a given user account, 26 // and inherit file handles across the dropping of privileges. 27 // 28 // NOTE: This package has only been tested on Linux. YMMV. 29 // 30 // NOTE: This package WILL NOT WORK on Windows. 31 // 32 // WARNING: if a process opens a config file as root, that file must be writable 33 // by root or system accounts only. The safest way to do this is change it to 34 // be root-owned with permissions 0644 (or 0600). 35 // 36 // Examples 37 // 38 // Opens privileged files and ports as root, then drops privileges 39 // 40 // https://www.tawesoft.co.uk/go/doc/drop/examples/drop/ 41 // 42 // 43 // Package Information 44 // 45 // License: MIT (see LICENSE.txt) 46 // 47 // Stable: candidate 48 // 49 // For more information, documentation, source code, examples, support, links, 50 // etc. please see https://www.tawesoft.co.uk/go and 51 // https://www.tawesoft.co.uk/go/drop 52 // 53 // 2021-07-09 54 // 55 // * The Inheritable interface has changed. It now has a Close() method. The 56 // Name() method has also been renamed String() to satisfy the stringer 57 // interface. 58 // 59 // * The Drop() function now returns an extra value before the error value. 60 // This `closer` can be used by the child process to close all Inheritable 61 // handles. Alternatively, it is possible to ignore this and close each 62 // handle by calling their Close() method. 63 // 64 // * The package now exports the builtins InheritableFile and 65 // InheritableNetListener that implement the Inheritable interface for 66 // Files and net.Listeners. These are created by the functions 67 // NewInheritableFile, NewInheritableTCPListener and 68 // NewInheritableUnixListener. 69 // 70 // * Drop() no longer panics on non-Linux platforms. However, it has only been 71 // tested on Linux so YMMV. It will continue to panic on Windows. Listeners 72 // also cannot be inherited on the JS platform target as they are not backed 73 // by files. 74 // 75 // 2021-03-17 76 // 77 // * Drop() now returns a (bool, error) 2-tuple. The first return value, 78 // if true, indicates that the caller should immediately exit. 79 // 80 // 2020-11-27 81 // 82 // * Drop() functionality has been moved to tawesoft.co.uk/go/drop with 83 // changes to Inheritables from a struct to an interface. 84 // 85 package drop // import "tawesoft.co.uk/go/drop" 86 87 // Code generated by internal. DO NOT EDIT. 88 // Instead, edit DESC.txt and run mkdocs.sh.