Documentation ¶
Index ¶
- Constants
- Variables
- func AgentPasswordHash(password string) string
- func AtomicWriteFile(filename string, contents []byte, perms os.FileMode) (err error)
- func AtomicWriteFileAndChange(filename string, contents []byte, change func(*os.File) error) (err error)
- func BasicAuthHeader(username, password string) http.Header
- func CommandString(args ...string) string
- func CopyFile(dest, source string) error
- func GetAddressForInterface(interfaceName string) (string, error)
- func GetHTTPClient(verify SSLHostnameVerification) *http.Client
- func GetIPv4Address(addresses []net.Addr) (string, error)
- func GetNonValidatingHTTPClient() *http.Client
- func GetValidatingHTTPClient() *http.Client
- func Gunzip(data []byte) ([]byte, error)
- func Gzip(data []byte) []byte
- func Home() string
- func IsUbuntu() bool
- func IsValidUUIDString(s string) bool
- func JoinServerPath(elem ...string) string
- func MakeFileURL(in string) string
- func NewHttpTLSTransport(tlsConfig *tls.Config) *http.Transport
- func NormalizePath(dir string) (string, error)
- func OSIsUnix(os string) bool
- func ParseBasicAuthHeader(h http.Header) (userid, password string, err error)
- func ParseSize(str string) (MB uint64, err error)
- func RandomBytes(n int) ([]byte, error)
- func RandomPassword() (string, error)
- func RandomSalt() (string, error)
- func ReadFileSHA256(filename string) (string, int64, error)
- func ReadSHA256(source io.Reader) (string, int64, error)
- func ReadYaml(path string, obj interface{}) error
- func ReplaceFile(source, destination string) error
- func RunCommand(command string, args ...string) (output string, err error)
- func SetHome(s string) error
- func ShQuote(s string) string
- func Timeit(action string) func()
- func UniqueDirectory(path, name string) (string, error)
- func UseMultipleCPUs()
- func UserHomeDir(userName string) (hDir string, err error)
- func UserPasswordHash(password string, salt string) string
- func WinCmdQuote(s string) string
- func WinPSQuote(s string) string
- func WriteYaml(path string, obj interface{}) error
- type Attempt
- type AttemptStrategy
- type Limiter
- type SSLHostnameVerification
- type UUID
Examples ¶
Constants ¶
const ( // VerifySSLHostnames ensures we verify the hostname on the certificate // matches the host we are connecting and is signed VerifySSLHostnames = SSLHostnameVerification(true) // NoVerifySSLHostnames informs us to skip verifying the hostname // matches a valid certificate NoVerifySSLHostnames = SSLHostnameVerification(false) )
const ( OSWindows = "windows" OSDarwin = "darwin" OSDragonfly = "dragonfly" OSFreebsd = "freebsd" OSLinux = "linux" OSNacl = "nacl" OSNetbsd = "netbsd" OSOpenbsd = "openbsd" OSSolaris = "solaris" )
These are the names of the operating systems recognized by Go.
const ( NoSuchUserErrRegexp = `user: unknown user [a-z0-9_-]*` NoSuchFileErrRegexp = `no such file or directory` )
The following are strings/regex-es which match common Unix error messages that may be returned in case of failed calls to the system. Any extra leading/trailing regex-es are left to be added by the developer.
Variables ¶
var CompatSalt = string([]byte{0x75, 0x82, 0x81, 0xca})
CompatSalt is because Juju 1.16 and older used a hard-coded salt to compute the password hash for all users and agents
var FastInsecureHash = false
FastInsecureHash specifies whether a fast, insecure version of the hash algorithm will be used. Changing this will cause PasswordHash to produce incompatible passwords. It should only be changed for testing purposes - to make tests run faster.
var MinAgentPasswordLength = base64.StdEncoding.EncodedLen(randomPasswordBytes)
MinAgentPasswordLength describes how long agent passwords should be. We require this length because we assume enough entropy in the Agent password that it is safe to not do extra rounds of iterated hashing.
var OSUnix = []string{ OSDarwin, OSDragonfly, OSFreebsd, OSLinux, OSNacl, OSNetbsd, OSOpenbsd, OSSolaris, }
OSUnix is the list of unix-like operating systems recognized by Go. See http://golang.org/src/path/filepath/path_unix.go.
var OutgoingAccessAllowed = true
OutgoingAccessAllowed determines whether connections other than localhost can be dialled.
var (
UUIDSnippet = block1 + "-" + block2 + "-" + version + block3 + "-" + variant + block4 + "-" + block5
)
regex for validating that the UUID matches RFC 4122. This package specifically generates and accepts version 4 UUIDs where the string representation has the digit 4 at the beginning of the third grouping, and one of the hex digits 8 through b at the beginning of the fourth grouping. http://www.ietf.org/rfc/rfc4122.txt
Functions ¶
func AgentPasswordHash ¶
AgentPasswordHash returns base64-encoded one-way hash of password. This is not suitable for User passwords because those will have limited entropy (see UserPasswordHash). However, since we generate long random passwords for agents, we can trust that there is sufficient entropy to prevent brute force search. And using a faster hash allows us to restart the state machines and have 1000s of agents log in in a reasonable amount of time.
func AtomicWriteFile ¶
AtomicWriteFile atomically writes the filename with the given contents and permissions, replacing any existing file at the same path.
func AtomicWriteFileAndChange ¶
func AtomicWriteFileAndChange(filename string, contents []byte, change func(*os.File) error) (err error)
AtomicWriteFileAndChange atomically writes the filename with the given contents and calls the given function after the contents were written, but before the file is renamed.
func BasicAuthHeader ¶
BasicAuthHeader creates a header that contains just the "Authorization" entry. The implementation was originally taked from net/http but this is needed externally from the http request object in order to use this with our websockets. See 2 (end of page 4) http://www.ietf.org/rfc/rfc2617.txt "To receive authorization, the client sends the userid and password, separated by a single colon (":") character, within a base64 encoded string in the credentials."
func CommandString ¶
CommandString flattens a sequence of command arguments into a string suitable for executing in a shell, escaping slashes, variables and quotes as necessary; each argument is double-quoted if and only if necessary.
func GetAddressForInterface ¶
GetAddressForInterface looks for the network interface and returns the IPv4 address from the possible addresses.
func GetHTTPClient ¶
func GetHTTPClient(verify SSLHostnameVerification) *http.Client
GetHTTPClient returns either a standard http client or non validating client depending on the value of verify.
func GetIPv4Address ¶
GetIPv4Address iterates through the addresses expecting the format from func (ifi *net.Interface) Addrs() ([]net.Addr, error)
func GetNonValidatingHTTPClient ¶
GetNonValidatingHTTPClient returns a new http.Client that does not verify the server's certificate chain and hostname.
func GetValidatingHTTPClient ¶
GetValidatingHTTPClient returns a new http.Client that verifies the server's certificate chain and hostname.
func Home ¶
func Home() string
Home returns the os-specific home path as specified in the environment.
func IsValidUUIDString ¶
IsValidUUIDString returns true, if the given string matches a valid UUID (version 4, variant 2).
func JoinServerPath ¶
JoinServerPath joins any number of path elements into a single path, adding a path separator (based on the current juju server OS) if necessary. The result is Cleaned; in particular, all empty strings are ignored.
func MakeFileURL ¶
MakeFileURL returns a file URL if a directory is passed in else it does nothing
func NewHttpTLSTransport ¶
NewHttpTLSTransport returns a new http.Transport constructed with the TLS config and the necessary parameters for Juju.
func NormalizePath ¶
NormalizePath expands a path containing ~ to its absolute form, and removes any .. or . path elements.
func OSIsUnix ¶
OSIsUnix determines whether or not the given OS name is one of the unix-like operating systems recognized by Go.
func ParseBasicAuthHeader ¶
ParseBasicAuth attempts to find an Authorization header in the supplied http.Header and if found parses it as a Basic header. See 2 (end of page 4) http://www.ietf.org/rfc/rfc2617.txt "To receive authorization, the client sends the userid and password, separated by a single colon (":") character, within a base64 encoded string in the credentials."
func ParseSize ¶
ParseSize parses the string as a size, in mebibytes.
The string must be a is a non-negative number with an optional multiplier suffix (M, G, T, P, E, Z, or Y). If the suffix is not specified, "M" is implied.
func RandomPassword ¶
RandomPassword generates a random base64-encoded password.
func RandomSalt ¶
RandomSalt generates a random base64 data suitable for using as a password salt The pbkdf2 guideline is to use 8 bytes of salt, so we do 12 raw bytes into 16 base64 bytes. (The alternative is 6 raw into 8 base64).
func ReadFileSHA256 ¶
ReadFileSHA256 is like ReadSHA256 but reads the contents of the given file.
func ReadSHA256 ¶
ReadSHA256 returns the SHA256 hash of the contents read from source (hex encoded) and the size of the source in bytes.
func ReadYaml ¶
ReadYaml unmarshals the yaml contained in the file at path into obj. See goyaml.Unmarshal.
func ReplaceFile ¶
ReplaceFile atomically replaces the destination file or directory with the source. The errors that are returned are identical to those returned by os.Rename.
func RunCommand ¶
RunCommand executes the command and return the combined output.
func ShQuote ¶
ShQuote quotes s so that when read by bash, no metacharacters within s will be interpreted as such.
func Timeit ¶
func Timeit(action string) func()
Start a timer, used for tracking time spent. Generally used with either defer, as in:
defer utils.Timeit("my func")()
Which will track how much time is spent in your function. Or if you want to track the time spent in a function you are calling then you would use:
toc := utils.Timeit("anotherFunc()") anotherFunc() toc()
This tracks nested calls by indenting the output, and will print out the full stack of timing when we reach the top of the stack.
func UniqueDirectory ¶
UniqueDirectory returns "path/name" if that directory doesn't exist. If it does, the method starts appending .1, .2, etc until a unique name is found.
func UseMultipleCPUs ¶
func UseMultipleCPUs()
UseMultipleCPUs sets GOMAXPROCS to the number of CPU cores unless it has already been overridden by the GOMAXPROCS environment variable.
func UserHomeDir ¶
UserHomeDir returns the home directory for the specified user, or the home directory for the current user if the specified user is empty.
func UserPasswordHash ¶
UserPasswordHash returns base64-encoded one-way hash password that is computationally hard to crack by iterating through possible passwords.
func WinCmdQuote ¶
WinCmdQuote quotes s so that when read by cmd.exe, no metacharacters within s will be interpreted as such.
func WinPSQuote ¶
WinPSQuote quotes s so that when read by powershell, no metacharacters within s will be interpreted as such.
Types ¶
type Attempt ¶
type Attempt struct {
// contains filtered or unexported fields
}
func (*Attempt) HasNext ¶
HasNext returns whether another attempt will be made if the current one fails. If it returns true, the following call to Next is guaranteed to return true.
Example ¶
package main import ( "time" gc "gopkg.in/check.v1" "github.com/juju/utils" ) func doSomething() (int, error) { return 0, nil } func shouldRetry(error) bool { return false } func doSomethingWith(int) {} func main() { // This example shows how Attempt.HasNext can be used to help // structure an attempt loop. If the godoc example code allowed // us to make the example return an error, we would uncomment // the commented return statements. attempts := utils.AttemptStrategy{ Total: 1 * time.Second, Delay: 250 * time.Millisecond, } for attempt := attempts.Start(); attempt.Next(); { x, err := doSomething() if shouldRetry(err) && attempt.HasNext() { continue } if err != nil { // return err return } doSomethingWith(x) } // return ErrTimedOut return } func (*utilsSuite) TestAttemptTiming(c *gc.C) { testAttempt := utils.AttemptStrategy{ Total: 0.25e9, Delay: 0.1e9, } want := []time.Duration{0, 0.1e9, 0.2e9, 0.2e9} got := make([]time.Duration, 0, len(want)) // avoid allocation when testing timing t0 := time.Now() for a := testAttempt.Start(); a.Next(); { got = append(got, time.Now().Sub(t0)) } got = append(got, time.Now().Sub(t0)) c.Assert(got, gc.HasLen, len(want)) const margin = 0.01e9 for i, got := range want { lo := want[i] - margin hi := want[i] + margin if got < lo || got > hi { c.Errorf("attempt %d want %g got %g", i, want[i].Seconds(), got.Seconds()) } } } func (*utilsSuite) TestAttemptNextHasNext(c *gc.C) { a := utils.AttemptStrategy{}.Start() c.Assert(a.Next(), gc.Equals, true) c.Assert(a.Next(), gc.Equals, false) a = utils.AttemptStrategy{}.Start() c.Assert(a.Next(), gc.Equals, true) c.Assert(a.HasNext(), gc.Equals, false) c.Assert(a.Next(), gc.Equals, false) a = utils.AttemptStrategy{Total: 2e8}.Start() c.Assert(a.Next(), gc.Equals, true) c.Assert(a.HasNext(), gc.Equals, true) time.Sleep(2e8) c.Assert(a.HasNext(), gc.Equals, true) c.Assert(a.Next(), gc.Equals, true) c.Assert(a.Next(), gc.Equals, false) a = utils.AttemptStrategy{Total: 1e8, Min: 2}.Start() time.Sleep(1e8) c.Assert(a.Next(), gc.Equals, true) c.Assert(a.HasNext(), gc.Equals, true) c.Assert(a.Next(), gc.Equals, true) c.Assert(a.HasNext(), gc.Equals, false) c.Assert(a.Next(), gc.Equals, false) }
Output:
type AttemptStrategy ¶
type AttemptStrategy struct { Total time.Duration // total duration of attempt. Delay time.Duration // interval between each try in the burst. Min int // minimum number of retries; overrides Total }
AttemptStrategy represents a strategy for waiting for an action to complete successfully.
func (AttemptStrategy) Start ¶
func (s AttemptStrategy) Start() *Attempt
Start begins a new sequence of attempts for the given strategy.
type Limiter ¶
type Limiter interface { // Acquire another unit of the resource. // Acquire returns false to indicate there is no more availability, // until another entity calls Release. Acquire() bool // AcquireWait requests a unit of resource, but blocks until one is // available. AcquireWait() // Release returns a unit of the resource. Calling Release when there // are no units Acquired is an error. Release() error }
Limiter represents a limited resource (eg a semaphore).
func NewLimiter ¶
type SSLHostnameVerification ¶
type SSLHostnameVerification bool
SSLHostnameVerification is used as a switch for when a given provider might use self-signed credentials and we should not try to verify the hostname on the TLS/SSL certificates
type UUID ¶
type UUID [16]byte
UUID represent a universal identifier with 16 octets.
func MustNewUUID ¶
func MustNewUUID() UUID
MustNewUUID returns a new uuid, if an error occurs it panics.
func UUIDFromString ¶
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
The deque package implements an efficient double-ended queue data structure called Deque.
|
The deque package implements an efficient double-ended queue data structure called Deque. |
The featureflag package gives other parts of Juju the ability to easily check to see if a feature flag has been defined.
|
The featureflag package gives other parts of Juju the ability to easily check to see if a feature flag has been defined. |
utils/filestorage provides types for abstracting and implementing a system that stores files, including their metadata.
|
utils/filestorage provides types for abstracting and implementing a system that stores files, including their metadata. |
On-disk mutex protecting a resource A lock is represented on disk by a directory of a particular name, containing an information file.
|
On-disk mutex protecting a resource A lock is represented on disk by a directory of a particular name, containing an information file. |
The jsonhttp package provides general functions for returning JSON responses to HTTP requests.
|
The jsonhttp package provides general functions for returning JSON responses to HTTP requests. |
The keyvalues package implements a set of functions for parsing key=value data, usually passed in as command-line parameters to juju subcommands, e.g.
|
The keyvalues package implements a set of functions for parsing key=value data, usually passed in as command-line parameters to juju subcommands, e.g. |
The parallel package provides utilities for running tasks concurrently.
|
The parallel package provides utilities for running tasks concurrently. |
This package provides convenience helpers on top of archive/tar to be able to tar/untar files with a functionality closer to gnu tar command.
|
This package provides convenience helpers on top of archive/tar to be able to tar/untar files with a functionality closer to gnu tar command. |
Package voyeur implements a concurrency-safe value that can be watched for changes.
|
Package voyeur implements a concurrency-safe value that can be watched for changes. |