summaryrefslogtreecommitdiff
path: root/extensions/pyfdisk.README
blob: 8b3b941be7a4d7bfb9a2941ebdee5ef67a4522a9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
Introduction
============

The pyfdisk.py module provides a basic Python wrapper around command-line
fdisk from util-linux, and some assorted related functions for querying
information from real disks or disk images.


YAML partition specification
============================

A YAML file may be loaded, using the function load_yaml(). This can contain
all the information needed to create a Device object which can then be
committed to disk.

The format of this file is as follows:

    start_offset: 2048
    partition_table_format: gpt
    partitions:
    - description: boot
      size: 1M
      fdisk_type: 0x0B
      filesystem: vfat
      boot: yes
      mountpoint: /boot
    - description: rootfs
      number: 3
      size: 10G
      filesystem: btrfs
      fdisk_type: 0x83
      mountpoint: /
    - description: src
      size: fill
      filesystem: ext4
      fdisk_type: 0x81
      mountpoint: /src

There are a couple of global attributes:

* 'start_offset': specifies the start sector of the first partition on the
                  device (default: 2048)

* 'partition_table_format': specifies the partition table format to be used
                            when creating the partition table. Possible format
                            strings are 'gpt', 'dos', or 'mbr' ('dos' and
                            'mbr' are interchangeable). (default: gpt)

Following this, up to 4 (for MBR) or 128 (for GPT) partitions can be
specified, in the list, 'partitions'. For partitions, 'size', 'fdisk_type' and
'filesystem' are required.

* 'size' is the size in bytes, or 'fill', which will expand the partition to
  fill any unused space. Multiple partitions with 'size: fill' will share the
  free space on the device. Human readable formatting can be used: K, M, G, T,
  for integer multiples (calculated as powers of 2^n)

* 'fdisk_type' is the fdisk partition type, specified as a hexadecimal value
  (default: 0x81)

* 'filesystem' specifies a filesystem to be created on the partition. It can
  be a filesystem with associated any mkfs.* tool, or 'none' for an
  unformatted partition.

Optional partition attributes include:

* 'number' is optional, and can be used to override the numbering of
  partitions, if it is desired to have partition numbering that differs from
  the physical order of the partitions on the disk.
      - For all un-numbered partitions, the physical order of partitions on the
        device is determined by the order in which they appear in the
        specification.
      - For any partitions without a specified number, partition numbering is
        handled automatically. In the example above, /boot is 1, /src is 2,
        and / is 3, even though the physical order differs.

* 'boot' sets the partition's bootable flag (currently only for MBR partition
  tables)

* 'mountpoint' specifies a mountpoint of a partition. One partition must
  have a '/' mountpoint to contain the rootfs, otherwise this is optional.
  Files present in the rootfs under the mount point for a given partition will
  be copied to the created partition.

load_yaml() produces a Device object, populated with any partitions contained
in the specification.


Objects
=======

Partition - An object containing properties of a partition

Device - An object holding information about a physical device, and the
         overall properties of the partitioning scheme. It contains a
         PartitionList holding the partitions on the device.

PartitionList - An object which holds a list of partitions on the disk. New
                partitions can be added to the list at any time. When the list
                is queried, properties of partitions which depend on the
                properties of the other partitions in the list, for example
                the size of a fill partition, or numbering, are recalculated,
                and an updated copy of a Partition object is returned.

Extent - An object which helps encapsulate sector dimensions for partitions
         and devices.


Quick start
===========

    >>> dev = pyfdisk.Device('test.img', 'fill')
    >>> print dev
    <Device: location=test.img, size=16777216, partitions: 0>
    >>> part = pyfdisk.Partition(size='1M', fdisk_type=0x81, filesystem='ext4', mountpoint='/test1')
    >>> part2 = pyfdisk.Partition(size='fill', filesystem='btrfs', mountpoint='/test2')
    >>> dev.add_partition(part)
    >>> dev.add_partition(part2)
    >>> print dev.partitionlist
    Partition
        size:       14663168
        fdisk type: 0x81
        filesystem: btrfs
        start:      4096
        end:        32734
        number:     2
        mountpoint: /test2
    Partition
        size:       1048576
        fdisk type: 0x81
        filesystem: ext4
        start:      2048
        end:        4095
        number:     1
        mountpoint: /test1
    >>> dev.commit()
    Creating GPT partition table on test.img

    $ fdisk -l test.img
    Disk test.img: 16 MiB, 16777216 bytes, 32768 sectors
    ...
    Device     Start   End Sectors Size Type
    test.img1   2048  4095    2048   1M Linux filesystem
    test.img2   4096 32734   28639  14M Linux filesystem