{ "content": [ { "type": "text", "text": "# cowpoke(1) (man)\n\n**Summary:** cowpoke - Build a Debian source package in a remote cowbuilder instance\n\n**Synopsis:** cowpoke [options] packagename.dsc\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| — | --create | — | Create the remote cowbuilder root if it does not already exist. If this option is not passed it is an error for the spec |\n| — | --no-return | — | Do not copy results of the build to RETURNDIR (overriding a path set for it in the configuration files). --dpkg-opts='op |\n| — | --version | — | Display the current version information. |\n\n## See Also\n\n- cowbuilder(1)\n- pbuilder(1)\n- ssh-agent(1)\n- sudoers(5)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (3 lines)\n- **DESCRIPTION** (5 lines)\n- **OPTIONS** (32 lines) — 3 subsections\n - --create (14 lines)\n - --no-return (52 lines)\n - --version (4 lines)\n- **CONFIGURATION OPTIONS** (6 lines) — 2 subsections\n - Global defaults (84 lines)\n - Arch and dist specific options (71 lines)\n- **CONFIGURATION FILES** (16 lines)\n- **COWBUILDER CONFIGURATION** (29 lines)\n- **NOTES** (9 lines)\n- **SEE ALSO** (3 lines)\n- **AUTHOR** (6 lines)\n\n## Full Content\n\n### NAME\n\ncowpoke - Build a Debian source package in a remote cowbuilder instance\n\n### SYNOPSIS\n\ncowpoke [options] packagename.dsc\n\n### DESCRIPTION\n\nUploads a Debian source package to a cowbuilder host and builds it, optionally also signing\nand uploading the result to an incoming queue.\n\n### OPTIONS\n\nThe following options are available:\n\n\n--arch=architecture\nSpecify the Debian architecture(s) to build for. A space separated list of architec‐\ntures may be used to build for all of them in a single pass. Valid arch names are\nthose returned by dpkg-architecture(1) for DEBBUILDARCH.\n\n\n--dist=distribution\nSpecify the Debian distribution(s) to build for. A space separated list of distribu‐\ntions may be used to build for all of them in a single pass. Either codenames (such\nas sid, or squeeze) or distribution names (such as unstable, or experimental) may be\nused, but you should usually stick to using one or the other consistently as this name\nmay be used in file paths and to locate old packages for comparison reporting.\n\nIt is now also possible to use locally defined names with this option, when used in\nconjunction with the BASEDIST option in a configuration file. This permits the main‐\ntenance and use of specially configured build chroots, which can source package depen‐\ndencies from the backports archives or a local repository, or have other unusual con‐\nfiguration options set, without polluting the chroots you use for clean package builds\nintended for upload to the main repositories. See the description of BASEDIST below.\n\n\n--buildd=host\nSpecify the remote host to build on.\n\n\n--buildd-user=name\nSpecify the remote user to build as.\n\n#### --create\n\nCreate the remote cowbuilder root if it does not already exist. If this option is not\npassed it is an error for the specified --dist or --arch to not have an existing cow‐‐\nbuilder root in the expected location.\n\nThe --buildd-user must have permission to create the RESULTDIR on the build host, or\nan admin with the necessary permission must first create it and give that user (or\nsome group they are in) write access to it, for this option to succeed.\n\n\n--return=[path]\nCopy results of the build to path. If path is not specified, then return them to the\ncurrent directory. The given path must exist, it will not be created.\n\n#### --no-return\n\nDo not copy results of the build to RETURNDIR (overriding a path set for it in the\nconfiguration files).\n\n\n--dpkg-opts='opt1 opt2 ...'\nSpecify additional options to be passed to dpkg-buildpackage(1). Multiple options are\ndelimited with spaces. This will override any options specified in DEBBUILDOPTS in\nthe build host's pbuilderrc.\n\n\n--create-opts='cowbuilder option'\nSpecify additional arguments to be passed verbatim to cowbuilder when a chroot is\nfirst created (using the --create option above). If multiple arguments need to be\npassed, this option should be specified separately for each of them.\n\nE.g., --create-opts \"--othermirror\" --create-opts \"deb http:// ...\"\n\nThis option will override any CREATEOPTS specified for a chroot in the cowpoke con‐\nfiguration files.\n\n\n--update-opts='cowbuilder option'\nSpecify additional arguments to be passed verbatim to cowbuilder if the base of the\nchroot is updated. If multiple arguments need to be passed, this option should be\nspecified separately for each of them.\n\nThis option will override any UPDATEOPTS specified for a chroot in the cowpoke con‐\nfiguration files.\n\n\n--build-opts='cowbuilder option'\nSpecify additional arguments to be passed verbatim to cowbuilder when a package build\nis performed. If multiple arguments need to be passed, this option should be speci‐\nfied separately for each of them.\n\nThis option will override any BUILDOPTS specified for a chroot in the cowpoke config‐\nuration files.\n\n\n--sign=keyid\nSpecify the key to sign packages with. This will override any SIGNKEYID specified\nfor a chroot in the cowpoke configuration files.\n\n\n--upload=queue\nSpecify the dput queue to upload signed packages to. This will override any UP‐‐\nLOADQUEUE specified for a chroot in the cowpoke configuration files.\n\n\n--help Display a brief summary of the available options and current configuration.\n\n#### --version\n\nDisplay the current version information.\n\n### CONFIGURATION OPTIONS\n\nWhen cowpoke is run the following configuration options are read from global, per-user, and\nper-project configuration files if present. File paths may be absolute or relative, the lat‐\nter being relative to the BUILDDUSER's home directory. Since the paths are typically quoted\nwhen used, tilde expansion will not be performed on them.\n\n#### Global defaults\n\nThese apply to every arch and dist in a single cowpoke invocation.\n\n\nBUILDDHOST\nThe network address or fqdn of the build machine where cowbuilder is configured. This\nmay be overridden by the --buildd command line option.\n\nBUILDDUSER\nThe unprivileged user name for operations on the build machine. This defaults to the\nlocal name of the user executing cowpoke (or to a username that is specified in your\nSSH configuration for BUILDDHOST), and may be overridden by the --buildd-user command\nline option.\n\nBUILDDARCH\nThe Debian architecture(s) to build for. This must match the DEBBUILDARCH of the\nbuild chroot being used. It defaults to the local machine architecture where cowpoke\nis executed, and may be overridden by the --arch command line option. A (quoted)\nspace separated list of architectures may be used here to build for all of them in a\nsingle pass.\n\nBUILDDDIST\nThe Debian distribution(s) to build for. A (quoted) space separated list of distribu‐\ntions may be used to build for all of them in a single pass. This may be overridden\nby the --dist command line option.\n\n\nINCOMINGDIR\nThe directory path on the build machine where the source package will initially be\nplaced. This must be writable by the BUILDDUSER.\n\nPBUILDERBASE\nThe filesystem root for all pbuilder CoW and result files. Arch and dist specific\nsubdirectories will normally be created under this. The apt cache and temporary build\ndirectory will also be located under this path.\n\n\nSIGNKEYID\nIf this option is set, it is expected to contain the gpg key ID to pass to debsign(1)\nif the packages are to be remotely signed. You will be prompted to confirm whether\nyou wish to sign the packages after all builds are complete. If this option is unset\nor an empty string, no attempt to sign packages will be made. It may be overridden on\nan arch and dist specific basis using the archdistSIGNKEYID option described below,\nor per-invocation with the --sign command line option.\n\n\nUPLOADQUEUE\nIf this option is set, it is expected to contain a 'host' specification for dput(1)\nwhich will be used to upload them after they are signed. You will be prompted to con‐\nfirm whether you wish to upload the packages after they are signed. If this option is\nunset or an empty string, no attempt to upload packages will be made. If SIGNKEYID\nis not set, this option will be ignored entirely. It may be overridden on an arch and\ndist specific basis using the archdistUPLOADQUEUE option described below, or per-\ninvocation with the --upload command line option.\n\n\n\nBUILDDROOTCMD\nThe command to use to gain root privileges on the remote build machine. If unset the\ndefault is sudo(8). This is only required to invoke cowbuilder and allow it to enter\nits chroot, so you may restrict this user to only being able to run that command with\nescalated privileges. Something like this in sudoers will enable invoking cowbuilder\nwithout an additional password entry required:\n\n\nyouruser ALL = NOPASSWD: /usr/sbin/cowbuilder\n\nAlternatively you could use SSH with a forwarded key, or whatever other mechanism\nsuits your local access policy. Using su -c isn't really suitable here due to its\nquoting requirements being somewhat different to the rest.\n\n\nDEBOOTSTRAP\nThe utility to use when creating a new build root. Alternatives are debootstrap or\ncdebootstrap.\n\n\nRETURNDIR\nIf set, package files resulting from the build will be copied to the path (local or\nremote) that this is set to, after the build completes. The path must exist, it will\nnot be created. This option is unset by default and can be overridden with --return\nor --no-return.\n\n#### Arch and dist specific options\n\nThese are variables of the form: $arch$distVAR which apply only for a particular target\narch/dist build.\n\n\narchdistRESULTDIR\nThe directory path on the build machine where the resulting packages (source and bi‐\nnary) will be found, and where older versions of the package that were built previ‐\nously may be found. If any such older packages exist, debdiff will be used to compare\nthe new package with the previous version after the build is complete, and the result\nwill be included in the build log. Files in it must be readable by the BUILDDUSER\nfor sanity checking with lintian(1) and debdiff(1), and for upload with dput(1). If\nthis option is not specified for some arch and dist combination then it will default\nto $PBUILDERBASE/$arch/$dist/result\n\n\narchdistBASEPATH\nThe directory where the CoW master files are to be found (or created if the --create\ncommand line option was passed). If this option is not specified for some arch or\ndist then it will default to $PBUILDERBASE/$arch/$dist/base.cow\n\n\narchdistBASEDIST\nThe code name to pass as the --distribution option for cowbuilder instead of dist.\nThis is necessary when dist is a locally significant name assigned to some specially\nconfigured build chroot, such as 'wheezybackports', and not the formal suite name of\na distro release known to debootstrap. This option cannot be overridden on the com‐\nmand line, since it would rarely, if ever, make any sense to change it for individual\ninvocations of cowpoke. If this option is not specified for an arch and dist combina‐\ntion then it will default to dist.\n\n\narchdistCREATEOPTS\nA bash array containing additional options to pass verbatim to cowbuilder when this\nchroot is created for the first time (using the --create option). This is useful when\noptions like --othermirror are wanted to create specialised chroot configurations such\nas 'wheezybackports'. By default this is unset. All values set in it will be over‐\nridden if the --create-opts option is passed on the command line.\n\nEach element in this array corresponds to a single argument (in the ARGV sense) that\nwill be passed to cowbuilder. This ensures that arguments which may contain white‐\nspace or have strange quoting requirements or other special characters will not be\nmangled before they get to cowbuilder.\n\nBash arrays are initialised using the following form:\n\nOPTS=( \"arg1\" \"arg 2\" \"--option\" \"value\" \"--opt=val\" \"etc. etc.\" )\n\n\narchdistUPDATEOPTS\nA bash array containing additional options to pass verbatim to cowbuilder each time\nthe base of this chroot is updated. It behaves similarly to the CREATEOPTS option\nabove, except for acting when the chroot is updated.\n\n\narchdistBUILDOPTS\nA bash array containing additional options to pass verbatim to cowbuilder each time a\npackage build is performed in this chroot. This is useful when you want to use some\noption like --twice which cowpoke does not directly need to care about. It otherwise\nbehaves similarly to UPDATEOPTS above except that it acts during the build phase of\ncowbuilder.\n\n\narchdistSIGNKEYID\nAn optional arch and dist specific override for the global SIGNKEYID option.\n\n\narchdistUPLOADQUEUE\nAn optional arch and dist specific override for the global UPLOADQUEUE option.\n\n### CONFIGURATION FILES\n\n/etc/cowpoke.conf\nGlobal configuration options. Will override hardcoded defaults.\n\n~/.cowpoke\nPer-user configuration options. Will override any global configuration.\n\n.cowpoke\nPer-project configuration options. Will override any per-user or global configuration\nif cowpoke is called from the directory where they exist.\n\nIf the environment variable COWPOKECONF is set, it specifies an additional configura‐\ntion file which will override all of those above. Options specified explicitly on the\ncommand line override all configuration files.\n\n### COWBUILDER CONFIGURATION\n\nThere is nothing particularly special required to configure a cowbuilder instance for use\nwith cowpoke. Simply create them in the flavour you require with `cowbuilder --create` ac‐\ncording to the cowbuilder documentation, then configure cowpoke with the user, arch, and path\ninformation required to access it, on the machines you wish to invoke it from (or alterna‐\ntively configure cowpoke with the path, arch and distribution information and pass the --cre‐‐\nate option to it on the first invocation). The build host running cowbuilder does not re‐\nquire cowpoke installed locally.\n\nThe build machine should have the lintian and devscripts packages installed for post-build\nsanity checking. Upon completion, the build log and the results of automated checks will be\nrecorded in the INCOMINGDIR. If you wish to upload signed packages the build machine will\nalso need dput(1) installed and configured to use the 'host' alias specified by UPLOADQUEUE.\nIf rsync(1) is available on both the local and build machine, then it will be used to trans‐\nfer the source package (this may save on some transfers of the orig.tar.* when building sub‐\nsequent Debian revisions).\n\nThe user executing cowpoke must have SSH access to the build machine as the BUILDDUSER.\nThat user must be able to invoke cowbuilder as root by using the BUILDDROOTCMD. Signing\nkeys are not required to be installed on the build machine (and will be ignored there if they\nare). If the package is signed, keys will be expected on the machine that executes cowpoke.\n\nWhen cowpoke is invoked, it will first attempt to update the cowbuilder image if that has not\nalready been done on the same day. This is checked by the presence or absence of a cow‐\nbuilder-$arch-$dist-update-log-$date file in the INCOMINGDIR. You may move, remove, or\ntouch this file if you wish the image to be updated more or less often than that. Its con‐\ntents log the output of cowbuilder during the update (or creation) of the build root.\n\n### NOTES\n\nSince cowbuilder creates a chroot, and to do that you need root, cowpoke also requires some\ndegree of root access. So all the horrible things that can go wrong with that may well one\nday rain down upon you. cowbuilder has been known to accidentally wipe out bind-mounted\nfilesystems outside the chroot, and worse than that can easily happen. So be careful, keep\ngood backups of things you don't want to lose on your build machine, and use cowpoke to keep\nall that on a machine that isn't your bleeding edge dev box with your last few hours of un‐\ncommitted work.\n\n### SEE ALSO\n\ncowbuilder(1), pbuilder(1), ssh-agent(1), sudoers(5)\n\n### AUTHOR\n\ncowpoke was written by Ron .\n\n\n\n\nApril 28, 2008 COWPOKE(1)\n\n" } ], "structuredContent": { "command": "cowpoke", "section": "1", "mode": "man", "summary": "cowpoke - Build a Debian source package in a remote cowbuilder instance", "synopsis": "cowpoke [options] packagename.dsc", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "", "long": "--create", "arg": null, "description": "Create the remote cowbuilder root if it does not already exist. If this option is not passed it is an error for the specified --dist or --arch to not have an existing cow‐‐ builder root in the expected location. The --buildd-user must have permission to create the RESULTDIR on the build host, or an admin with the necessary permission must first create it and give that user (or some group they are in) write access to it, for this option to succeed. --return=[path] Copy results of the build to path. If path is not specified, then return them to the current directory. The given path must exist, it will not be created." }, { "flag": "", "long": "--no-return", "arg": null, "description": "Do not copy results of the build to RETURNDIR (overriding a path set for it in the configuration files). --dpkg-opts='opt1 opt2 ...' Specify additional options to be passed to dpkg-buildpackage(1). Multiple options are delimited with spaces. This will override any options specified in DEBBUILDOPTS in the build host's pbuilderrc. --create-opts='cowbuilder option' Specify additional arguments to be passed verbatim to cowbuilder when a chroot is first created (using the --create option above). If multiple arguments need to be passed, this option should be specified separately for each of them. E.g., --create-opts \"--othermirror\" --create-opts \"deb http:// ...\" This option will override any CREATEOPTS specified for a chroot in the cowpoke con‐ figuration files. --update-opts='cowbuilder option' Specify additional arguments to be passed verbatim to cowbuilder if the base of the chroot is updated. If multiple arguments need to be passed, this option should be specified separately for each of them. This option will override any UPDATEOPTS specified for a chroot in the cowpoke con‐ figuration files. --build-opts='cowbuilder option' Specify additional arguments to be passed verbatim to cowbuilder when a package build is performed. If multiple arguments need to be passed, this option should be speci‐ fied separately for each of them. This option will override any BUILDOPTS specified for a chroot in the cowpoke config‐ uration files. --sign=keyid Specify the key to sign packages with. This will override any SIGNKEYID specified for a chroot in the cowpoke configuration files. --upload=queue Specify the dput queue to upload signed packages to. This will override any UP‐‐ LOADQUEUE specified for a chroot in the cowpoke configuration files. --help Display a brief summary of the available options and current configuration." }, { "flag": "", "long": "--version", "arg": null, "description": "Display the current version information." } ], "examples": [], "see_also": [ { "name": "cowbuilder", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/cowbuilder/1/json" }, { "name": "pbuilder", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pbuilder/1/json" }, { "name": "ssh-agent", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/ssh-agent/1/json" }, { "name": "sudoers", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/sudoers/5/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 5, "subsections": [] }, { "name": "OPTIONS", "lines": 32, "subsections": [ { "name": "--create", "lines": 14, "long": "--create" }, { "name": "--no-return", "lines": 52, "long": "--no-return" }, { "name": "--version", "lines": 4, "long": "--version" } ] }, { "name": "CONFIGURATION OPTIONS", "lines": 6, "subsections": [ { "name": "Global defaults", "lines": 84 }, { "name": "Arch and dist specific options", "lines": 71 } ] }, { "name": "CONFIGURATION FILES", "lines": 16, "subsections": [] }, { "name": "COWBUILDER CONFIGURATION", "lines": 29, "subsections": [] }, { "name": "NOTES", "lines": 9, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 6, "subsections": [] } ] } }