cmd

Documentation

Overview

Package cmd implements commands for running pydio services

Index

• Variables
• func Execute()
• type CellsVersion
• type Service
• type Tags

Variables

var (
	IsFork       bool
	EnvPrefixOld = "pydio"
	EnvPrefixNew = "cells"
)

var (
	FilterStartTags    []string
	FilterStartExclude []string
)

var AclCmd = &cobra.Command{
	Use:   "acl",
	Short: "Manage access control lists",
	Long: `
DESCRIPTION

  ACLs are managed in a dedicated micro-service.

  It is simpler to manage them in the frontend, but you can use this command to create/delete/search ACLs directly.
  ACLs are used to grant permissions to a given node Uuid for a given Role.
`,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

AclCmd represents the acl command

var AdminCmd = &cobra.Command{
	Use:   "admin",
	Short: "Direct Read/Write access to Cells data",
	Long: `
DESCRIPTION

  Admin commands allow direct access to Cells data.
	
  These commands require a running Cells instance. They connect directly to low-level services
  using gRPC connections. They are not authenticated.
`,
	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
		replaceKeys := map[string]string{}

		cmd.Flags().VisitAll(func(flag *pflag.Flag) {
			key := flag.Name
			if replace, ok := replaceKeys[flag.Name]; ok {
				key = replace
			}
			flag.Usage += " [" + strings.ToUpper("$"+EnvPrefixNew+"_"+key) + "]"
			viper.BindPFlag(key, flag)
		})

		nats.Init()

		handleRegistry()

		handleBroker()

		handleTransport()

		return nil
	},
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

AdminCmd groups the data manipulation commands The sub-commands are connecting via gRPC to a **running** Cells instance.

var ConfigCmd = &cobra.Command{
	Use:   "config",
	Short: "Configuration manager",
	Long: `
DESCRIPTION

  This set of commands provides programmatic access to stored configurations

`,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

ConfigCmd represents the config command

var ConfigureCmd = &cobra.Command{
	Use:     "configure",
	Aliases: []string{"install"},
	Short:   "Setup required configurations",
	Long: `
DESCRIPTION

  Launch the configuration process of Pydio Cells.

REQUIREMENTS

  You must have an available MySQL database, along with a privileged user (for instance 'pydio').
  Supported databases are:
   - MariaDB version 10.3 and above,
   - MySQL version 5.7 and above (except 8.0.22 that has a bug preventing Cells to run correctly).

  As recommended by database documentation, tune the 'max_connections' parameter to a value in line
  with your production database server specifications. For reference, the default value of 151 will have a 
  maximum memory usage of about 575MB, but will not scale up for a multiple users load in production.

BROWSER-BASED INSTALLER

  If you are on a desktop machine, pick browser-based installation at first prompt, or you can force it with:
  $ ` + os.Args[0] + ` configure --bind default
 
  The installer opens a web page on port 8080 with a wizard for you to provide various configuration parameters, 
  including DB connection info and the login/password of the main administrator.

  In case where default port is busy, you can choose another one via the 'bind' flag, for instance:
  $ ` + os.Args[0] + ` configure --bind 0.0.0.0:12345
  or   
  $ ` + os.Args[0] + ` configure --bind <your server IP or FQDN>:12345

  After browser configuration, all microservices are started automatically and you can directly start using Cells. 
  It is yet good practice to stop the installer and restart Cells in normal mode before going live.

COMMAND-LINE INSTALLER

  If you are more a shell person, you can perform the configuration process directly using this CLI (using the '--cli' 
  flag or by choosing so at first prompt). You will then be able to choose to either use the default bindings for the 
  embedded webserver or adapt these to your specific setup.
 
  You can always reconfigure the webserver bindings afterwards by calling this command:
  $ ` + os.Args[0] + ` configure sites
  See corresponding inline documentation for further details.

AUTOMATED PROVISIONING

  For automated, non-interactive installation, you can pass a YAML or a JSON config file that contains all necessary 
  information, please refer to the documentation on https://pydio.com .

 `,
	PreRunE: func(cmd *cobra.Command, args []string) error {
		if err := checkFdlimit(); err != nil {
			return err
		}

		replaceKeys := map[string]string{
			"yaml": "install_yaml",
			"json": "install_json",
			"cli":  "install_cli",
		}

		cmd.Flags().VisitAll(func(flag *pflag.Flag) {
			key := flag.Name
			if replace, ok := replaceKeys[flag.Name]; ok {
				key = replace
			}
			flag.Usage += " [" + strings.ToUpper("$"+EnvPrefixNew+"_"+key) + "]"
			viper.BindPFlag(key, flag)
		})

		niBindUrl = viper.GetString("bind")
		niExtUrl = viper.GetString("external")
		niNoTls = viper.GetBool("no_tls")
		niModeCli = viper.GetBool("install_cli")
		niCertFile = viper.GetString("tls_cert_file")
		niKeyFile = viper.GetString("tls_key_file")
		niLeEmailContact = viper.GetString("le_email")
		niLeAcceptEula = viper.GetBool("le_agree")
		niLeUseStagingCA = viper.GetBool("le_staging")
		niYamlFile = viper.GetString("install_yaml")
		niJsonFile = viper.GetString("install_json")
		niExitAfterInstall = viper.GetBool("exit_after_install")

		return nil
	},
	Run: func(cmd *cobra.Command, args []string) {

		cmd.Println("")
		cmd.Println("\033[1mWelcome to " + common.PackageLabel + " installation\033[0m ")
		cmd.Println(common.PackageLabel + " (v" + common.Version().String() + ") will be configured to run on this machine.")
		cmd.Println("Make sure to prepare access and credentials to a MySQL 5.6+ (or MariaDB equivalent) server.")
		cmd.Println("Pick your installation mode when you are ready.")
		cmd.Println("")

		var proxyConf *install.ProxyConfig
		var err error

		micro := config.Get("ports", common.ServiceMicroApi).Int()
		if micro == 0 {
			micro = net.GetAvailablePort()
			config.Set(micro, "ports", common.ServiceMicroApi)
			err = config.Save("cli", "Install / Setting default Ports")
			fatalIfError(cmd, err)
		}

		if niYamlFile != "" || niJsonFile != "" || niBindUrl != "" {

			installConf, err := nonInteractiveInstall(cmd, args)
			fatalIfError(cmd, err)
			if installConf.FrontendLogin != "" {

				return
			}

			proxyConf = installConf.GetProxyConfig()

		} else {
			if !niModeCli {

				p := promptui.Select{Label: "Installation mode", Items: []string{"Browser-based (requires a browser access)", "Command line (performed in this terminal)"}}
				installIndex, _, err := p.Run()
				fatalIfError(cmd, err)
				niModeCli = installIndex == 1
			}

			sites, err := config.LoadSites()
			fatalIfError(cmd, err)
			proxyConf = sites[0]

			proxyConf, err = switchDefaultTls(cmd, proxyConf, niNoTls)
			fatalIfError(cmd, err)

			if !niModeCli {
				var message string
				proxyConf, message, err = checkDefaultBusy(cmd, proxyConf, true)
				fatalIfError(cmd, err)
				if message != "" {
					cmd.Println(promptui.IconWarn, message)
				}
			}
		}

		if niModeCli {
			_, err := cliInstall(cmd, proxyConf)
			fatalIfError(cmd, err)
			return
		}

		performBrowserInstall(cmd, proxyConf)

		if niExitAfterInstall {
			cmd.Println("")
			cmd.Println(promptui.IconGood + "\033[1m Installation Finished: installation server will stop\033[0m")
			cmd.Println("")
			return
		}

		cmd.Println("")
		cmd.Println(promptui.IconGood + "\033[1m Installation Finished: server will restart\033[0m")
		cmd.Println("")

		plugins.Init(cmd.Context())

		registry.Default.AfterInit()

		if s, err := registry.Default.ListServices(); err != nil {
			cmd.Print("Could not retrieve list of services")
			os.Exit(0)
		} else {
			allServices = s
		}

		excludes := []string{
			common.ServiceMicroApi,
			common.ServiceRestNamespace_ + common.ServiceInstall,
		}

		for _, service := range allServices {
			ignore := false
			for _, ex := range excludes {
				if service.Name() == ex {
					ignore = true
				}
			}
			if service.Regexp() != nil {
				ignore = true
			}
			if !ignore {
				if service.RequiresFork() {
					if !service.AutoStart() {
						continue
					}
					go service.ForkStart(cmd.Context())
				} else {
					go service.Start(cmd.Context())
				}
			}
		}

		<-cmd.Context().Done()

		ticker := time.Tick(1 * time.Second)

		timeout := time.After(10 * time.Second)

	loop:
		for {
			select {
			case <-ticker:
				process := registry.Default.GetCurrentProcess()
				childrenProcesses := registry.Default.GetCurrentChildrenProcesses()
				if (process == nil || len(process.Services) == 0) && len(childrenProcesses) == 0 {
					break loop
				}
				continue
			case <-timeout:
				break loop
			}
		}
	},
}

ConfigureCmd launches a wizard (either in this CLI or in your web browser) to configure a new instance of Pydio Cells.

var DataCmd = &cobra.Command{
	Use:    "data",
	Hidden: true,
	Short:  "Directly interact with a datasource",
	Long: `
DESCRIPTION

  Commands for managing indexed data.

  Data are indexed in the various data sources you may have defined, and aggregated into a unique tree by
  the tree service. This command allows you among others to launch a full re-synchronisation of a given datasource.
`,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

DataCmd is kept hidden for backward compatibility

var DocCmd = &cobra.Command{
	Use:    "doc",
	Hidden: true,
	Short:  "Manage documentation about Cells and this CLI tool",
	Long:   ``,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

var FilesCmd = &cobra.Command{
	Use:   "files",
	Short: "Directly manage files and metadata on the nodes",
	Long: `
DESCRIPTION

  Manage metadata that enrich some of the nodes.
  Metadata are stored as simple key/values and attached to a node UUID.

`,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

var RootCmd = &cobra.Command{
	Use:   os.Args[0],
	Short: "Secure File Sharing for business",
	Long: `
DESCRIPTION

  Cells is a comprehensive sync & share solution for your collaborators. 
  Open-source software deployed on-premise or in a private cloud.

CONFIGURE

  For the very first run, use '` + os.Args[0] + ` configure' to load browser-based or command-line based installation wizard. 
  Services will start at the end of the installation.

RUN

  Run '$ ` + os.Args[0] + ` start' to load all services.

WORKING DIRECTORIES

  By default, application data is stored under the standard OS application dir : 
  
   - Linux: ${USER_HOME}/.config/pydio/cells
   - Darwin: ${USER_HOME}/Library/Application Support/Pydio/cells
   - Windows: ${USER_HOME}/ApplicationData/Roaming/Pydio/cells

  You can customize the various storage locations with the following ENV variables : 
  
   - CELLS_WORKING_DIR : replace the whole standard application dir
   - CELLS_DATA_DIR : replace the location for storing default datasources (default CELLS_WORKING_DIR/data)
   - CELLS_LOG_DIR : replace the location for storing logs (default CELLS_WORKING_DIR/logs)
   - CELLS_SERVICES_DIR : replace location for services-specific data (default CELLS_WORKING_DIR/services) 

LOGS LEVEL

  By default, logs are outputted in console format at the Info level. You can set the --log flag or set the 
  CELLS_LOGS_LEVEL environment variable to one of the following values:
   - debug, info, error : logs are written in console format with the according level
   - production : logs are written in json format, for usage with a log aggregator tool.

SERVICES DISCOVERY

  Microservices need a registry mechanism to discover each other. Cells ships and starts its own NATS (nats.io) 
  implementation, unless a 'gnatsd' service is already running, in which case it will be detected.
`,
	PersistentPreRun: func(cmd *cobra.Command, args []string) {

		if cmd.Long == StartCmd.Long {
			common.LogCaptureStdOut = true
		}

		for _, skip := range infoCommands {
			if cmd.Name() == skip {
				return
			}
		}
	},
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

RootCmd represents the base command when called without any subcommands

var StartCmd = &cobra.Command{
	Use:   "start",
	Short: "Start one or more services",
	Long: `
DESCRIPTION

  Start one or more services on this machine. 
  $ ` + os.Args[0] + ` start [flags] args...

  Select specific services with regular expressions in the additional arguments. No arguments will start all services available (see 'ps' command). 
   - The -t/--tags flag may limit to only a certain category of services, use lowercase like broker, idm, data, etc...  
   - The -x/--exclude flag may exclude one or more services
  Both flags may be used in conjunction with the regexp arguments.

REQUIREMENTS
  
  Ulimit: set a number of allowed open files greater or equal to 2048.
  For production use, a minimum of 8192 is recommended (see ulimit -n).

  Setcap: if you intend to bind the server to standard http ports (80, 443), 
  you must grant necessary permissions on cells binary with this command:
  $ sudo setcap 'cap_net_bind_service=+ep' <path to your binary>    

EXAMPLES

  1. Start all Cells services
  $ ` + os.Args[0] + ` start

  2. Start only services starting with grpc
  $ ` + os.Args[0] + ` start pydio.grpc

  3. Start only services for scheduler
  $ ` + os.Args[0] + ` start --tag=scheduler

  4. Start whole plateform except the roles service
  $ ` + os.Args[0] + ` start --exclude=pydio.grpc.idm.roles

`,
	PreRunE: func(cmd *cobra.Command, args []string) error {

		if !IsFork {
			if err := checkFdlimit(); err != nil {
				return err
			}
		}

		replaceKeys := map[string]string{
			"log":  "logs_level",
			"fork": "is_fork",
		}
		cmd.Flags().VisitAll(func(flag *pflag.Flag) {
			key := flag.Name
			if replace, ok := replaceKeys[flag.Name]; ok {
				key = replace
			}
			flag.Usage += " [" + strings.ToUpper("$"+EnvPrefixNew+"_"+key) + "]"
			viper.BindPFlag(key, flag)
		})

		nats.Init()

		metrics.Init()

		handleRegistry()

		handleBroker()

		handleTransport()

		handleSignals()

		plugins.Init(cmd.Context())

		registry.Default.Filter(func(s registry.Service) bool {
			for _, exclude := range FilterStartExclude {
				re := regexp.MustCompile(exclude)

				if strings.HasPrefix(s.Name(), exclude) || re.MatchString(s.Name()) {
					return true
				}
			}

			return false
		})

		registry.Default.Filter(func(s registry.Service) bool {

			for _, exclude := range FilterStartExclude {
				if exclude == startTagUnique && s.MustBeUnique() {
					return true
				}
			}
			for _, t := range FilterStartTags {
				if t == startTagUnique && s.MustBeUnique() {
					registry.ProcessStartTags = append(registry.ProcessStartTags, "t:"+t)
					return false
				} else {
					for _, st := range s.Tags() {
						if t == st {
							registry.ProcessStartTags = append(registry.ProcessStartTags, "t:"+t)
							return false
						}
					}
				}
			}

			return len(FilterStartTags) > 0
		})

		registry.Default.Filter(func(s registry.Service) bool {
			for _, arg := range args {
				reArg := regexp.MustCompile(arg)
				if reArg.MatchString(s.Name()) {
					registry.ProcessStartTags = append(registry.ProcessStartTags, "s:"+s.Name())
					return false
				}
				if s.MatchesRegexp(arg) {
					registry.ProcessStartTags = append(registry.ProcessStartTags, "s:"+s.Name())
					return false
				}
			}
			return len(args) > 0
		})

		registry.Default.Filter(func(s registry.Service) bool {
			if len(args) == 0 && s.Regexp() != nil {
				return true
			}
			return false
		})

		for _, x := range FilterStartExclude {
			registry.ProcessStartTags = append(registry.ProcessStartTags, "x:"+x)
		}

		if s, err := registry.Default.ListServices(); err != nil {
			return fmt.Errorf("Could not retrieve list of services")
		} else {
			allServices = s
		}

		initServices()

		return nil
	},

	Run: func(cmd *cobra.Command, args []string) {

		if a, _ := config.GetDatabase("default"); a == "" {
			var crtUser string
			if u, er := user.Current(); er == nil {
				crtUser = "(currently running as '" + u.Username + "')"
			}
			cmd.Println("****************************************************************************************")
			cmd.Println("# ")
			cmd.Println("# " + promptui.IconBad + " Oops, cannot find a valid configuration for the database!")
			cmd.Println("# ")
			cmd.Println("# A - Before first start, make sure to first run the basic configuration steps:")
			cmd.Println("#     $> " + os.Args[0] + " configure")
			cmd.Println("# ")
			cmd.Println("# B - If you have already installed, maybe the configuration file is not accessible.")
			cmd.Println("#     Working Directory is " + config.ApplicationWorkingDir())
			cmd.Println("#     If you did not set the CELLS_WORKING_DIR environment variable, make sure you are ")
			cmd.Println("#     launching the process as the correct OS user " + crtUser + ".")
			cmd.Println("# ")
			cmd.Println("****************************************************************************************")
			cmd.Println("")
			pr := promptui.Prompt{IsConfirm: true, Label: "Do you want to run '" + os.Args[0] + " configure' now"}
			if _, e := pr.Run(); e != nil {
				cmd.Println("Exiting now...")
			} else {
				ConfigureCmd.Run(cmd, args)
			}
			return
		}

	loopstart:
		for _, service := range allServices {
			if !IsFork && service.RequiresFork() {
				if !service.AutoStart() {
					continue
				}
				go service.ForkStart(cmd.Context())
			} else {
				go service.Start(cmd.Context())
			}

			select {
			case <-cmd.Context().Done():
				break loopstart
			default:
				continue
			}
		}

		<-cmd.Context().Done()

		ticker := time.Tick(1 * time.Second)

		timeout := time.After(10 * time.Second)

	loop:
		for {
			select {
			case <-ticker:
				process := registry.Default.GetCurrentProcess()
				childrenProcesses := registry.Default.GetCurrentChildrenProcesses()
				if (process == nil || len(process.Services) == 0) && len(childrenProcesses) == 0 {
					break loop
				}
				continue
			case <-timeout:
				break loop
			}
		}
	},
}

StartCmd represents the start command

var ToolsCmd = &cobra.Command{
	Use:   "tools",
	Short: "Additional tools",
	Long: `
DESCRIPTION

  Various commands that do not require a running Cells instance.
`,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

ToolsCmd are tools that do not need a running Cells instance

var UserCmd = &cobra.Command{
	Use:   "user",
	Short: "Manage users",
	Long: `
DESCRIPTION

  Manage users from command line by calling the dedicated services.
`,
	Run: func(cmd *cobra.Command, args []string) {
		cmd.Help()
	},
}

Functions

func Execute

func Execute()

Execute adds all child commands to the root command and sets flags appropriately. This is called by main.main(). It only needs to happen once to the rootCmd.

Types

type CellsVersion

type CellsVersion struct {
	//Distribution string
	PackageLabel string
	Version      string
	BuildTime    string
	GitCommit    string
	OS           string
	Arch         string
	GoVersion    string
}

CellsVersion contains version information for the current running binary

type Service

type Service interface {
	Name() string
	IsRunning() bool
}

type Tags

type Tags struct {
	Name     string
	Services map[string]Service
	Tags     map[string]*Tags
}