github.com/singularityware/singularity@v3.1.1+incompatible/docs/content.go (about) 1 // Copyright (c) 2017-2019, Sylabs Inc. All rights reserved. 2 // This software is licensed under a 3-clause BSD license. Please consult the 3 // LICENSE.md file distributed with the sources of this project regarding your 4 // rights to use or distribute this software. 5 6 //TODO Provide some guidelines for writing these docs 7 8 package docs 9 10 // Global content for help and man pages 11 const ( 12 13 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 14 // main singularity command 15 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 16 SingularityUse string = `singularity [global options...]` 17 SingularityShort string = ` 18 Linux container platform optimized for High Performance Computing (HPC) and 19 Enterprise Performance Computing (EPC)` 20 SingularityLong string = ` 21 Singularity containers provide an application virtualization layer enabling 22 mobility of compute via both application and environment portability. With 23 Singularity one is capable of building a root file system that runs on any 24 other Linux system where Singularity is installed.` 25 SingularityExample string = ` 26 $ singularity help <command> 27 Additional help for any Singularity subcommand can be seen by appending 28 the subcommand name to the above command.` 29 30 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 31 // build 32 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 BuildUse string = `build [local options...] <IMAGE PATH> <BUILD SPEC>` 34 BuildShort string = `Build a Singularity image` 35 BuildLong string = ` 36 37 IMAGE PATH: 38 39 When Singularity builds the container, output can be one of a few formats: 40 41 default: The compressed Singularity read only image format (default) 42 sandbox: This is a read-write container within a directory structure 43 44 note: It is a common workflow to use the "sandbox" mode for development of the 45 container, and then build it as a default Singularity image for production 46 use. The default format is immutable. 47 48 BUILD SPEC: 49 50 The build spec target is a definition (def) file, local image, or URI that can 51 be used to create a Singularity container. Several different local target 52 formats exist: 53 54 def file : This is a recipe for building a container (examples below) 55 directory: A directory structure containing a (ch)root file system 56 image: A local image on your machine (will convert to sif if 57 it is legacy format) 58 59 Targets can also be remote and defined by a URI of the following formats: 60 61 library:// an image library (default https://cloud.sylabs.io/library) 62 docker:// a Docker registry (default Docker Hub) 63 shub:// a Singularity registry (default Singularity Hub)` 64 65 BuildExample string = ` 66 67 DEF FILE BASE OS: 68 69 Library: 70 Bootstrap: library 71 From: debian:9 72 73 Docker: 74 Bootstrap: docker 75 From: tensorflow/tensorflow:latest 76 IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT 77 78 Singularity Hub: 79 Bootstrap: shub 80 From: singularityhub/centos 81 82 YUM/RHEL: 83 Bootstrap: yum 84 OSVersion: 7 85 MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64/ 86 Include: yum 87 88 Debian/Ubuntu: 89 Bootstrap: debootstrap 90 OSVersion: trusty 91 MirrorURL: http://us.archive.ubuntu.com/ubuntu/ 92 93 Local Image: 94 Bootstrap: localimage 95 From: /home/dave/starter.img 96 97 Scratch: 98 Bootstrap: scratch # Populate the container with a minimal rootfs in %setup 99 100 DEFFILE SECTIONS: 101 102 %pre 103 echo "This is a scriptlet that will be executed on the host, as root before" 104 echo "the container has been bootstrapped. This section is not commonly used." 105 106 %setup 107 echo "This is a scriptlet that will be executed on the host, as root, after" 108 echo "the container has been bootstrapped. To install things into the container" 109 echo "reference the file system location with $SINGULARITY_ROOTFS." 110 111 %post 112 echo "This scriptlet section will be executed from within the container after" 113 echo "the bootstrap/base has been created and setup." 114 115 %test 116 echo "Define any test commands that should be executed after container has been" 117 echo "built. This scriptlet will be executed from within the running container" 118 echo "as the root user. Pay attention to the exit/return value of this scriptlet" 119 echo "as any non-zero exit code will be assumed as failure." 120 exit 0 121 122 %runscript 123 echo "Define actions for the container to be executed with the run command or" 124 echo "when container is executed." 125 126 %startscript 127 echo "Define actions for container to perform when started as an instance." 128 129 %labels 130 HELLO MOTO 131 KEY VALUE 132 133 %files 134 /path/on/host/file.txt /path/on/container/file.txt 135 relative_file.txt /path/on/container/relative_file.txt 136 137 %environment 138 LUKE=goodguy 139 VADER=badguy 140 HAN=someguy 141 export HAN VADER LUKE 142 143 %help 144 This is a text file to be displayed with the run-help command. 145 146 COMMANDS: 147 148 Build a sif file from a Singularity recipe file: 149 $ singularity build /tmp/debian0.sif /path/to/debian.def 150 151 Build a sif image from the Library: 152 $ singularity build /tmp/debian1.sif library://debian:latest 153 154 Build a base sandbox from DockerHub, make changes to it, then build sif 155 $ singularity build --sandbox /tmp/debian docker://debian:latest 156 $ singularity exec --writable /tmp/debian apt-get install python 157 $ singularity build /tmp/debian2.sif /tmp/debian` 158 159 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 160 // Cache 161 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 162 CacheUse string = `cache` 163 CacheShort string = `Manage the local cache` 164 CacheLong string = ` 165 Manage your local singularity cache. You can list/clean using the specific types.` 166 CacheExample string = ` 167 All group commands have their own help output: 168 169 $ singularity cache 170 $ singularity cache --help` 171 172 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 173 // Cache clean 174 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 175 CacheCleanUse string = `clean [clean options...]` 176 CacheCleanShort string = `Clean your local Singularity cache` 177 CacheCleanLong string = ` 178 This will clean your local cache (stored at $HOME/.singularity/cache if SINGULARITY_CACHEDIR is not set). 179 By default only blob cache is cleaned, use '--all' to clean the entire cache.` 180 CacheCleanExample string = ` 181 All group commands have their own help output: 182 183 $ singularity help cache clean --name cache_name.sif 184 $ singularity help cache clean --type=library,oci 185 $ singularity cache clean --help` 186 187 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 // Cache List 189 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 190 CacheListUse string = `list [list options...]` 191 CacheListShort string = `List your local Singularity cache` 192 CacheListLong string = ` 193 This will list your local cache (stored at $HOME/.singularity/cache if SINGULARITY_CACHEDIR is not set).` 194 CacheListExample string = ` 195 All group commands have their own help output: 196 197 $ singularity help cache list 198 $ singularity help cache list --type=library,oci 199 $ singularity cache list --help` 200 201 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 202 // key 203 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 204 KeyUse string = `key [key options...]` 205 206 // keys : for the hidden `keys` command 207 KeysUse string = `keys [keys options...]` 208 KeyShort string = `Manage OpenPGP keys` 209 KeyLong string = ` 210 The 'key' command allows you to manage local OpenPGP key stores by creating 211 a new store and new key pairs. You can also list available keys from the 212 default store. Finally, the key command offers subcommands to communicate 213 with an HKP key server to fetch and upload public keys.` 214 KeyExample string = ` 215 All group commands have their own help output: 216 217 $ singularity help key newpair 218 $ singularity key list --help` 219 220 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 221 // key newpair 222 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 223 KeyNewPairUse string = `newpair` 224 KeyNewPairShort string = `Create a new OpenPGP key pair` 225 KeyNewPairLong string = ` 226 The 'key newpair' command allows you to create a new key or public/private 227 keys to be stored in the default user local key store location (e.g., 228 $HOME/.singularity/sypgp).` 229 KeyNewPairExample string = ` 230 $ singularity key newpair` 231 232 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 233 // key list 234 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 235 KeyListUse string = `list` 236 KeyListShort string = `List keys from the default key store` 237 KeyListLong string = ` 238 The 'key list' command allows you to list public/private key pairs from the 239 default user local key store location (e.g., $HOME/.singularity/sypgp).` 240 KeyListExample string = ` 241 $ singularity key list` 242 243 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 244 // key search 245 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 246 KeySearchUse string = `search [search options...] <search_string>` 247 KeySearchShort string = `Search for keys matching string argument` 248 KeySearchLong string = ` 249 The 'key search' command allows you to connect to a key server and look for 250 public keys matching the string argument passed to the command line.` 251 KeySearchExample string = ` 252 $ singularity key search sylabs.io` 253 254 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 255 // key pull 256 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 KeyPullUse string = `pull [pull options...] <fingerprint>` 258 KeyPullShort string = `Fetch an OpenPGP public key from a key server` 259 KeyPullLong string = ` 260 The 'key pull' command allows you to connect to a key server look for and 261 download a public key. Key rings are stored into (e.g., 262 $HOME/.singularity/sypgp).` 263 KeyPullExample string = ` 264 $ singularity key pull D87FE3AF5C1F063FCBCC9B02F812842B5EEE5934` 265 266 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 267 // key push 268 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 269 KeyPushUse string = `push [push options...] <fingerprint>` 270 KeyPushShort string = `Upload an OpenPGP public key to a key server` 271 KeyPushLong string = ` 272 The 'key push' command allows you to connect to a key server and upload 273 public keys from the local key store.` 274 KeyPushExample string = ` 275 $ singularity key push D87FE3AF5C1F063FCBCC9B02F812842B5EEE5934` 276 277 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 278 // capability 279 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 280 CapabilityUse string = `capability` 281 CapabilityShort string = `Manage Linux capabilities for users and groups` 282 CapabilityLong string = ` 283 Capabilities allow you to have fine grained control over the permissions that 284 your containers need to run. 285 286 NOTE: capability add/drop commands requires root to run.` 287 CapabilityExample string = ` 288 All group commands have their own help output: 289 290 $ singularity help capability add 291 $ singularity capability add --help` 292 293 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 294 // capability add 295 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 296 CapabilityAddUse string = `add [add options...] <capabilities>` 297 CapabilityAddShort string = `Add capabilities to a user or group (requires root)` 298 CapabilityAddLong string = ` 299 Add Linux capabilities to a user or group. NOTE: This command requires root to run. 300 301 The capabilities argument must be separated by commas and is not case sensitive. 302 303 To see available capabilities, type "singularity capability avail" or refer to 304 capabilities manual "man 7 capabilities".` 305 CapabilityAddExample string = ` 306 $ sudo singularity capability add --user nobody AUDIT_READ,chown 307 $ sudo singularity capability add --group nobody cap_audit_write 308 309 To add all capabilities to a user: 310 311 $ sudo singularity capability add --user nobody all` 312 313 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 314 // capability drop 315 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 316 CapabilityDropUse string = `drop [drop options...] <capabilities>` 317 CapabilityDropShort string = `Remove capabilities from a user or group (requires root)` 318 CapabilityDropLong string = ` 319 Remove Linux capabilities from an user/group. NOTE: This command requires root to run. 320 321 The capabilities argument must be separated by commas and is not case sensitive. 322 323 To see available capabilities, type "singularity capability avail" or refer to 324 capabilities manual "man 7 capabilities"` 325 CapabilityDropExample string = ` 326 $ sudo singularity capability drop --user nobody AUDIT_READ,CHOWN 327 $ sudo singularity capability drop --group nobody audit_write 328 329 To drop all capabilities for a user: 330 331 $ sudo singularity capability drop --user nobody all` 332 333 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 334 // capability list 335 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 336 CapabilityListUse string = `list [user/group]` 337 CapabilityListShort string = `Show capabilities for a given user or group` 338 CapabilityListLong string = ` 339 Show the capabilities for a user or group.` 340 CapabilityListExample string = ` 341 To list capabilities set for user or group nobody: 342 343 $ singularity capability list nobody 344 345 To list capabilities for all users/groups: 346 347 $ singularity capability list` 348 349 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 350 // capability avail 351 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 352 CapabilityAvailUse string = `avail [capabilities]` 353 CapabilityAvailShort string = `Show description for available capabilities` 354 CapabilityAvailLong string = ` 355 Show description for available Linux capabilities.` 356 CapabilityAvailExample string = ` 357 Show description for all available capabilities: 358 359 $ singularity capability avail 360 361 Show CAP_CHOWN description: 362 363 $ singularity capability avail CAP_CHOWN 364 365 Show CAP_CHOWN/CAP_NET_RAW description: 366 367 $ singularity capability avail CAP_CHOWN,CAP_NET_RAW` 368 369 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 370 // exec 371 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 372 formats string = ` 373 374 *.sif Singularity Image Format (SIF). Native to Singularity 3.0+ 375 376 *.sqsh SquashFS format. Native to Singularity 2.4+ 377 378 *.img ext3 format. Native to Singularity versions < 2.4. 379 380 directory/ sandbox format. Directory containing a valid root file 381 system and optionally Singularity meta-data. 382 383 instance://* A local running instance of a container. (See the instance 384 command group.) 385 386 library://* A container hosted on a Library (default 387 https://cloud.sylabs.io/library) 388 389 docker://* A container hosted on Docker Hub 390 391 shub://* A container hosted on Singularity Hub` 392 ExecUse string = `exec [exec options...] <container> <command>` 393 ExecShort string = `Run a command within a container` 394 ExecLong string = ` 395 singularity exec supports the following formats:` + formats 396 ExecExamples string = ` 397 $ singularity exec /tmp/debian.sif cat /etc/debian_version 398 $ singularity exec /tmp/debian.sif python ./hello_world.py 399 $ cat hello_world.py | singularity exec /tmp/debian.sif python 400 $ sudo singularity exec --writable /tmp/debian.sif apt-get update 401 $ singularity exec instance://my_instance ps -ef 402 $ singularity exec library://centos cat /etc/os-release` 403 404 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 405 // instance 406 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 407 InstanceUse string = `instance` 408 InstanceShort string = `Manage containers running as services` 409 InstanceLong string = ` 410 Instances allow you to run containers as background processes. This can be 411 useful for running services such as web servers or databases.` 412 InstanceExample string = ` 413 All group commands have their own help output: 414 415 $ singularity help instance start 416 $ singularity instance start --help` 417 418 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 419 // instance list 420 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 421 InstanceListUse string = `list [list options...]` 422 InstanceListShort string = `List all running and named Singularity instances` 423 InstanceListLong string = ` 424 The instance list command allows you to view the Singularity container 425 instances that are currently running in the background.` 426 InstanceListExample string = ` 427 $ singularity instance list 428 DAEMON NAME PID CONTAINER IMAGE 429 test 11963 /home/mibauer/singularity/sinstance/test.sif 430 431 $ sudo singularity instance list -u mibauer 432 DAEMON NAME PID CONTAINER IMAGE 433 test 11963 /home/mibauer/singularity/sinstance/test.sif 434 test2 16219 /home/mibauer/singularity/sinstance/test.sif` 435 436 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 437 // instance start 438 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 439 InstanceStartUse string = `start [start options...] <container path> <instance name> [startscript args...]` 440 InstanceStartShort string = `Start a named instance of the given container image` 441 InstanceStartLong string = ` 442 The instance start command allows you to create a new named instance from an 443 existing container image that will begin running in the background. If a 444 startscript is defined in the container metadata the commands in that script 445 will be executed with the instance start command as well. You can optionally 446 pass arguments to startscript 447 448 singularity instance start accepts the following container formats` + formats 449 InstanceStartExample string = ` 450 $ singularity instance start /tmp/my-sql.sif mysql 451 452 $ singularity shell instance://mysql 453 Singularity my-sql.sif> pwd 454 /home/mibauer/mysql 455 Singularity my-sql.sif> ps 456 PID TTY TIME CMD 457 1 pts/0 00:00:00 sinit 458 2 pts/0 00:00:00 bash 459 3 pts/0 00:00:00 ps 460 Singularity my-sql.sif> 461 462 $ singularity instance stop /tmp/my-sql.sif mysql 463 Stopping /tmp/my-sql.sif mysql` 464 465 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 466 // instance stop 467 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 468 InstanceStopUse string = `stop [stop options...] [instance]` 469 InstanceStopShort string = `Stop a named instance of a given container image` 470 InstanceStopLong string = ` 471 The command singularity instance stop allows you to stop and clean up a named, 472 running instance of a given container image.` 473 InstanceStopExample string = ` 474 $ singularity instance start my-sql.sif mysql1 475 $ singularity instance start my-sql.sif mysql2 476 $ singularity instance stop mysql* 477 Stopping mysql1 instance of my-sql.sif (PID=23845) 478 Stopping mysql2 instance of my-sql.sif (PID=23858) 479 480 $ singularity instance start my-sql.sif mysql1 481 482 Force instance to shutdown 483 $ singularity instance stop -f mysql1 (may corrupt data) 484 485 Send SIGTERM to the instance 486 $ singularity instance stop -s SIGTERM mysql1 487 $ singularity instance stop -s TERM mysql1 488 $ singularity instance stop -s 15 mysql1` 489 490 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 491 // pull 492 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 493 PullUse string = `pull [pull options...] [output file] <URI>` 494 PullShort string = `Pull an image from a URI` 495 PullLong string = ` 496 The 'pull' command allows you to download or build a container from a given 497 URI. Supported URIs include: 498 499 library: Pull an image from the currently configured library 500 library://[user[collection/[container[:tag]]]] 501 502 docker: Pull an image from Docker Hub 503 docker://user/image:tag 504 505 shub: Pull an image from Singularity Hub to CWD 506 shub://user/image:tag` 507 PullExample string = ` 508 From Sylabs cloud library 509 $ singularity pull alpine.sif library://alpine:latest 510 511 From Docker 512 $ singularity pull tensorflow.sif docker://tensorflow/tensorflow:latest 513 514 From Shub 515 $ singularity pull singularity-images.sif shub://vsoch/singularity-images` 516 517 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 518 // push 519 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 520 PushUse string = `push [push options...] <container image> library://[user[collection/[container[:tag]]]]` 521 PushShort string = `Push a container to a Library URI` 522 PushLong string = ` 523 The Singularity push command allows you to upload your sif image to a library 524 of your choosing` 525 PushExample string = ` 526 $ singularity push /home/user/my.sif library://user/collection/my.sif:latest` 527 528 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 529 // search 530 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 531 SearchUse string = `search [search options...] <search query>` 532 SearchShort string = `Search a Library for images` 533 SearchLong string = ` 534 The Singularity search command allows you to search within a container library 535 of your choosing. The container library defaults to 536 https://library.sylabs.io when no other library argument is given.` 537 SearchExample string = ` 538 $ singularity search lolcow` 539 540 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 541 // run 542 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 543 RunUse string = `run [run options...] <container>` 544 RunShort string = `Run the user-defined default command within a container` 545 RunLong string = ` 546 This command will launch a Singularity container and execute a runscript 547 if one is defined for that container. The runscript is a metadata file within 548 the container that contains shell commands. If the file is present (and 549 executable) then this command will execute that file within the container 550 automatically. All arguments following the container name will be passed 551 directly to the runscript. 552 553 singularity run accepts the following container formats:` + formats 554 RunExamples string = ` 555 # Here we see that the runscript prints "Hello world: " 556 $ singularity exec /tmp/debian.sif cat /singularity 557 #!/bin/sh 558 echo "Hello world: " 559 560 # It runs with our inputs when we run the image 561 $ singularity run /tmp/debian.sif one two three 562 Hello world: one two three 563 564 # Note that this does the same thing 565 $ ./tmp/debian.sif one two three` 566 567 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 568 // shell 569 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 570 ShellUse string = `shell [shell options...] <container>` 571 ShellShort string = `Run a shell within a container` 572 ShellLong string = ` 573 singularity shell supports the following formats:` + formats 574 ShellExamples string = ` 575 $ singularity shell /tmp/Debian.sif 576 Singularity/Debian.sif> pwd 577 /home/gmk/test 578 Singularity/Debian.sif> exit 579 580 $ singularity shell -C /tmp/Debian.sif 581 Singularity/Debian.sif> pwd 582 /home/gmk 583 Singularity/Debian.sif> ls -l 584 total 0 585 Singularity/Debian.sif> exit 586 587 $ sudo singularity shell -w /tmp/Debian.sif 588 $ sudo singularity shell --writable /tmp/Debian.sif 589 590 $ singularity shell instance://my_instance 591 592 $ singularity shell instance://my_instance 593 Singularity: Invoking an interactive shell within container... 594 Singularity container:~> ps -ef 595 UID PID PPID C STIME TTY TIME CMD 596 ubuntu 1 0 0 20:00 ? 00:00:00 /usr/local/bin/singularity/bin/sinit 597 ubuntu 2 0 0 20:01 pts/8 00:00:00 /bin/bash --norc 598 ubuntu 3 2 0 20:02 pts/8 00:00:00 ps -ef` 599 600 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 601 // sign 602 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 603 SignUse string = `sign [sign options...] <image path>` 604 SignShort string = `Attach a cryptographic signature to an image` 605 SignLong string = ` 606 The sign command allows a user to create a cryptographic signature on either a 607 single data object or a list of data objects within the same SIF group. By 608 default without parameters, the command searches for the primary partition and 609 creates a verification block that is then added to the SIF container file.` 610 SignExample string = ` 611 $ singularity sign container.sif` 612 613 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 614 // verify 615 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 616 VerifyUse string = `verify [verify options...] <image path>` 617 VerifyShort string = `Verify cryptographic signatures attached to an image` 618 VerifyLong string = ` 619 The verify command allows a user to verify cryptographic signatures on SIF 620 container files. There may be multiple signatures for data objects and 621 multiple data objects signed. By default the command searches for the primary 622 partition signature. If found, a list of all verification blocks applied on 623 the primary partition is gathered so that data integrity (hashing) and 624 signature verification is done for all those blocks.` 625 VerifyExample string = ` 626 $ singularity verify container.sif` 627 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 628 // Run-help 629 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 630 RunHelpUse string = `run-help <image path>` 631 RunHelpShort string = `Show the user-defined help for an image` 632 RunHelpLong string = ` 633 Show the help for an image. 634 635 The help text is from the '%help' section of the definition file. If you are using the '--apps' option, 636 the help text is instead from that app's '%apphelp' section.` 637 RunHelpExample string = ` 638 $ cat my_container.def 639 Bootstrap: docker 640 From: busybox 641 642 %help 643 Some help for this container 644 645 %apphelp foo 646 Some help for application 'foo' in this container 647 648 $ sudo singularity build my_container.sif my_container.def 649 Using container recipe deffile: my_container.def 650 [...snip...] 651 Cleaning up... 652 653 $ singularity run-help my_container.sif 654 655 Some help for this container 656 657 $ singularity run-help --app foo my_container.sif 658 659 Some help for application in this container` 660 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 661 // Inspect 662 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 663 InspectUse string = `inspect [inspect options...] <image path>` 664 InspectShort string = `Show metadata for an image` 665 InspectLong string = ` 666 Inspect will show you labels, environment variables, and scripts associated 667 with the image determined by the flags you pass.` 668 InspectExample string = ` 669 $ singularity inspect ubuntu.sif` 670 671 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 672 // Apps 673 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 674 AppsUse string = `apps <image path>` 675 AppsShort string = `List available apps within a container` 676 AppsLong string = ` 677 List applications (apps) installed in a container, located at 678 /scif/apps. See http://containers-ftw.org/SCI-F/ 679 680 To access apps, use shell, exec, run, inspect with --app <appname> 681 682 The following environment variables are available to you when called 683 from the shell inside the container. The top variables are relevant 684 to the active app (--app <app>) and the bottom available for all 685 apps regardless of the active app: 686 687 ACTIVE APP ENVIRONMENT: 688 689 SCIF_APPNAME the name of the application 690 SCIF_APPROOT the application base (/scif/apps/<app>) 691 SCIF_APPMETA the application metadata folder 692 SCIF_APPDATA the data base folder for active app 693 SCIF_APPINPUT expected input folder within data base folder 694 SCIF_APPOUTPUT the output data folder within data base folder 695 696 GLOBAL APP ENVIRONMENT: 697 698 SCIF_DATA scif defined data base for all apps (/scif/data) 699 SCIF_APPS scif defined install bases for all apps (/scif/apps) 700 SCIF_APPROOT_<app> root for application <app> 701 SCIF_APPDATA_<app> data root for application <app> 702 703 704 For additional help, please visit our public documentation pages which are 705 found at: 706 707 https://www.sylabs.io/docs/` 708 AppsExample string = ` 709 $ singularity apps ubuntu.img 710 bar 711 foo` 712 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 713 // Test 714 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 715 RunTestUse string = `test [exec options...] <image path>` 716 RunTestShort string = `Run the user-defined tests within a container` 717 RunTestLong string = ` 718 The 'test' command allows you to execute a testscript (if available) inside of 719 a given container 720 721 NOTE: 722 For instances if there is a daemon process running inside the container, 723 then subsequent container commands will all run within the same 724 namespaces. This means that the --writable and --contain options will not 725 be honored as the namespaces have already been configured by the 726 'singularity start' command. 727 ` 728 RunTestExample string = ` 729 Set the '%test' section with a definition file like so: 730 %test 731 echo "hello from test" "$@" 732 733 $ singularity test /tmp/debian.sif command 734 hello from test command 735 736 For additional help, please visit our public documentation pages which are 737 found at: 738 739 https://www.sylabs.io/docs/` 740 741 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 742 // OCI 743 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 744 OciUse string = `oci` 745 OciShort string = `Manage OCI containers` 746 OciLong string = ` 747 Allow you to manage containers from OCI bundle directories. 748 749 NOTE: all oci commands requires to run as root` 750 OciExample string = ` 751 All group commands have their own help output: 752 753 $ singularity oci create -b ~/bundle mycontainer 754 $ singularity oci start mycontainer` 755 756 OciCreateUse string = `create [create options...] <container_ID>` 757 OciCreateShort string = `Create a container from a bundle directory (root user only)` 758 OciCreateLong string = ` 759 Create invoke create operation to create a container instance from an OCI bundle directory` 760 OciCreateExample string = ` 761 $ singularity oci create -b ~/bundle mycontainer` 762 763 OciStartUse string = `start <container_ID>` 764 OciStartShort string = `Start container process (root user only)` 765 OciStartLong string = ` 766 Start invoke start operation to start a previously created container identified by container ID.` 767 OciStartExample string = ` 768 $ singularity oci start mycontainer` 769 770 OciStateUse string = `state <container_ID>` 771 OciStateShort string = `Query state of a container (root user only)` 772 OciStateLong string = ` 773 State invoke state operation to query state of a created/running/stopped container identified by container ID.` 774 OciStateExample string = ` 775 $ singularity oci state mycontainer` 776 777 OciKillUse string = `kill <container_ID> [-s] signal` 778 OciKillShort string = `Kill a container (root user only)` 779 OciKillLong string = ` 780 Kill invoke kill operation to kill processes running within container identified by container ID.` 781 OciKillExample string = ` 782 $ singularity oci kill mycontainer INT 783 $ singularity oci kill mycontainer -s INT` 784 785 OciDeleteUse string = `delete <container_ID>` 786 OciDeleteShort string = `Delete container (root user only)` 787 OciDeleteLong string = ` 788 Delete invoke delete operation to delete resources that were created for container identified by container ID.` 789 OciDeleteExample string = ` 790 $ singularity oci delete mycontainer` 791 792 OciAttachUse string = `attach <container_ID>` 793 OciAttachShort string = `Attach console to a running container process (root user only)` 794 OciAttachLong string = ` 795 Attach will attach console to a running container process running within container identified by container ID.` 796 OciAttachExample string = ` 797 $ singularity oci attach mycontainer` 798 799 OciExecUse string = `exec <container_ID> <command> <args>` 800 OciExecShort string = `Execute a command within container (root user only)` 801 OciExecLong string = ` 802 Exec will execute the provided command/arguments within container identified by container ID.` 803 OciExecExample string = ` 804 $ singularity oci exec mycontainer id` 805 806 OciRunUse string = `run [run options...] <container_ID>` 807 OciRunShort string = `Create/start/attach/delete a container from a bundle directory (root user only)` 808 OciRunLong string = ` 809 Run will invoke equivalent of create/start/attach/delete commands in a row.` 810 OciRunExample string = ` 811 $ singularity oci run -b ~/bundle mycontainer 812 813 is equivalent to : 814 815 $ singularity oci create -b ~/bundle mycontainer 816 $ singularity oci start mycontainer 817 $ singularity oci attach mycontainer 818 $ singularity oci delete mycontainer` 819 820 OciUpdateUse string = `update [update options...] <container_ID>` 821 OciUpdateShort string = `Update container cgroups resources (root user only)` 822 OciUpdateLong string = ` 823 Update will update cgroups resources for the specified container ID. 824 Container must be in a RUNNING or CREATED state.` 825 OciUpdateExample string = ` 826 $ singularity oci update --from-file /tmp/cgroups-update.json mycontainer 827 828 or to update from stdin : 829 830 $ cat /tmp/cgroups-update.json | singularity oci update --from-file - mycontainer` 831 832 OciPauseUse string = `pause <container_ID>` 833 OciPauseShort string = `Suspends all processes inside the container (root user only)` 834 OciPauseLong string = ` 835 Pause will suspend all processes for the specified container ID.` 836 OciPauseExample string = ` 837 $ singularity oci pause mycontainer` 838 839 OciResumeUse string = `resume <container_ID>` 840 OciResumeShort string = `Resumes all processes previously paused inside the container (root user only)` 841 OciResumeLong string = ` 842 Resume will resume all processes previously paused for the specified container ID.` 843 OciResumeExample string = ` 844 $ singularity oci resume mycontainer` 845 846 OciMountUse string = `mount <sif_image> <bundle_path>` 847 OciMountShort string = `Mount create an OCI bundle from SIF image (root user only)` 848 OciMountLong string = ` 849 Mount will mount and create an OCI bundle from a SIF image.` 850 OciMountExample string = ` 851 $ singularity oci mount /tmp/example.sif /var/lib/singularity/bundles/example` 852 853 OciUmountUse string = `umount <bundle_path>` 854 OciUmountShort string = `Umount delete bundle (root user only)` 855 OciUmountLong string = ` 856 Umount will umount an OCI bundle previously mounted with singularity oci mount.` 857 OciUmountExample string = ` 858 $ singularity oci umount /var/lib/singularity/bundles/example` 859 )